See L</REQUEST TYPES>.
-=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
+=item C<< CGI::Auth::Flexible::srcdump_dir_cpio($cgi,$verifier,$dumpdir,$dir,$outfn,$how,$script) >>
+
+Helper function for implementing the C<srcdump_process_item> hook.
+Generates a tarball using cpio and includes it in the prepared source
+code distribution.
+
+The arguments are mostly the same as for that hook. C<$dir> is the
+root directory at which to start the archive. C<$how> is a short text
+string which will be mentioned in the log.
+
+C<$script> is a shell script fragment which must output a
+nul-separated list of filenames (e.g. the output of C<find -print0>).
+
+xxx blah blah
+
+=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible-> >>
Hashes the supplied data using the hash function specified by the
C<hash_algorithm> setting, and converts the result to a string of hex
%implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
would be a legal call. (However, the settings hash is not exposed.)
+When a hook's default implementation is mentioned and named, that
+function won't also be described in the section on the module's
+functions.
+
=over
=head2 GENERAL SETTINGS
description C<gettext("Password")>, and a login submit button (with
description C<gettext("Login")>.
-Default is available as the class function C<gen_plain_login_form>.
+Default is available as the module function C<gen_plain_login_form>.
=item C<gen_login_link>($cgi,$authreq))
<a href="http:...">gettext(Log in again to continue.)</a>
-Default is available as the class function C<gen_plain_login_link>.
+Default is available as the module function C<gen_plain_login_link>.
=item C<gen_postmainpage_form>($cgi,$authreq,$params))
<input type="submit" ... value=getext('Continue')>
-Default is available as the class function C<gen_postmainpage_form>.
+Default is available as the module function C<gen_postmainpage_form>.
=item C<gen_start_html>($cgi,$authreq,$title)
[gen_source_link_html].
</address>
-Default is available as the class function C<gen_plain_footer_html>.
+Default is available as the module function C<gen_plain_footer_html>.
=item C<gen_licence_link_html>($cgi,$authreq)>
downloading the licence, and returns:
<a href="...">GNU Affero GPL</a>
-Default is available as the class function C<gen_plain_licence_link_html>.
+Default is available as the module function C<gen_plain_licence_link_html>.
=item C<gen_source_link_html>($cgi,$authreq)>
downloading the source, and returns:
<a href="...">Source available</a>
-Default is available as the class function C<gen_plain_source_link_html>.
+Default is available as the module function C<gen_plain_source_link_html>.
=item C<form_entry_size>
If this is a relative path, it is in C<dir>.
+=item C<srcdump_dump($cgi,$authreq,$srcobj)>
+
+Dump the source code (C<$srcobj='source'> or licence data
+(C<$srcobj='licence'>). The default implementation checks that
+C<$srcobj> has reasonable syntax and uses the files C<$srcobj.data>
+and C<$srcobj.ctype> with the C<dump> hook.
+
+=item C<dump($cgi,$authreq,$contenttype,$datafilehandle)>
+
+Responds to the request by sending the contents of $datafilehandle
+(which should just have been opened) and specifying a content type of
+$contenttype.
+
+The default implmentation uses the C<print> hook, and also calls
+C<$cgi->header('-type' => $contenttype>, and is available as the
+module function C<dump_plain>.
+
+=item C<srcdump_prepare($cgi,$verifier)>
+
+Prepares the source code for download when requested. Invoked by
+C<new_verifier>, always, immediately before it returns the
+just-created verifier object.
+
+The default implementation is the module function
+C<srcdump_dirscan_prepare>, which prepares a manifest, licence file
+and source code tarball of tarballs, as follows:
+
+It processes each entry in the return value from C<srcdump_listitems>.
+These are the software's include directories and any other directories
+containing source code. It handles C<.> specially (see
+C<srcdump_filter_cwd>).
+
+For each entry it looks, relative to that, for the licence as a file
+with a name mentioned in C<srcdump_licence_files>. The first such
+file found is considered to be the licence. It then calls the hook
+C<srcdump_process_item> for the entry.
+
+The licence, a manifest file, and all the outputs generated by the
+calls to C<srcdump_process_item>, are tarred up and compressed as a
+single source tarball.
+
+It uses the directory named by C<srcdump_path> as its directory for
+working and output files. It uses the filename patterns
+C<generate.*>, C<licence.*>, C<s.[a-z][a-z][a-z].*>, C<manifest.*>,
+C<source.*> in that directory.
+
+=item C<srcdump_process_item>($cgi,$verifier,$dumpdir,$item,\&outfn,\$needlicence,\%dirsdone)>
+
+Processes a single include directory or software entry, so as to
+include the source code found there. Called only by the default
+implementation of C<srcdump_prepare>.
+
+C<$dumpdir> is the directory for working and output files. C<$item>
+is the real (no symlinks) absolute path to the item.
+
+C<\$needlicence> is a ref to a scalar: this scalar is undef if we have
+already found the licence file; otherwise it is the filename to which
+the licence should be copied. If the referent is undef on entry,
+C<srcdump_process_item> needs to see if it finds the licence; if it
+does it should copy it to the named file and then set the scalar to
+undef.
+
+C<\%dirsdone> is a ref to the hash used by C<srcdump_prepare> to avoid
+including a single directory more than once. If
+C<srcdump_process_item> decides to process a directory other than
+C<$item> it should check this hash with the real absolute path of the
+other directoy as a key: if the hash entry is true, it has already
+been done and should be skipped; otherwise the hash entry should be set.
+
+C<\&outfn> is a coderef which C<srcdump_process_item> should call each
+time it wants to generate a file which should be included as part of
+the source code. It should be called using one of these patterns:
+ $outfn->("message for log");
+ $outfile = $outfn->("message for log", "extension");
+The former simply logs this message (along with the associated
+C<$item>, so there is no need to mention that). The latter logs the
+message but also generates and returns a filename which should then
+be created and filled with some appropriate data. C<"extension">
+should be a string for the file extension, eg C<"txt">. The output
+can be written directly to the named file: there is no need to
+write to a temporary file and rename.
+
+The default implementation is the module function
+C<srcdump_process_item>. It searches the item and its parent
+directories for a vcs metadata directory (one of the names in
+C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
+(after checking and updaeing C<%dirsdone>).
+Otherwise it calls the C<srcdump_novcs> hook.
+
+=item C<srcdump_novcs($cgi,$verifier,$dumpdir,$item,$outfn)>
+
+Called by the default implementation of C<srcdump_process_item>, with
+the same arguments, if it doesn't find vcs metadata.
+
+The default implementation is the module function C<srcdump_novcs>.
+
+If C<$item> is a directory, it uses C<srcdump_dir_cpio> to prepare a
+tarball of all the files under C<$item> which have the world read bit
+set. Directories are not included (and their permissions are
+disregarded). The contents of C<srcdump_excludes> are excluded.
+
+If it's a plain file it uses C<srcdump_file> to include the file.
+
+=item C<srcdump_byvcs($cgi,$verifier,$dumpdir,$item,$outfn,$vcs)>
+
+Called by the default implementation of C<srcdump_process_item>, with
+the same arguments, if it finds vcs metadata. The additional argument
+C<$vcs> is derived from the entry of C<srcump_vcs_dirs> which was
+used: it's the first sequence of word characters, lowercased.
+
+The default implementation is the module function C<srcdump_byvcs>.
+It simply calls C<srcdump_dir_cpio> with the script from the setting
+C<srcdump_vcsscript_$vcs>.
+
+
+ which is defined
+
+xxx conditions on listitems implied by srcdump_dirscan_prepare
+xxx listitems enoent behaviour
+The de
+
+xxx syntax of srcdump_excludes
+
+
=back
~ian / cgi-auth-flexible.git / blobdiff