path: root/Master/tlpkg/doc/Perl-API.txt

API for Perl Modules for new infra
==================================

NOTE: THE DEFINITIVE DOCUMENTATION IS IN THE PM FILES AS POD DOCUMENTATION!!

Module TeXLive::TLPSRC
----------------------

PLEASE SEE THE MANPAGE OF TeXLive::TLPSRC which is MORE UP 2 DATE!!!!

Constructor:
	TeXLive::TLPSRC->new;
	TeXLive::TLPSRC->new( name => "foobar", shortdesc => "The foobar package", ...);

Input/Output
	$tlsrc->from_file("package.tlsrc");
	$tlsrc->writeout
		without arg to stdout
		with arg to filehandle

Read/Write functions (with argument set, without arg read)

	$tlsrc->name
	$tlsrc->category
	$tlsrc->shortdesc
	$tlsrc->longdesc
	$tlsrc->catalogue
	$tlsrc->srcpatterns
	$tlsrc->docpatterns
	$tlsrc->runpatterns
	$tlsrc->binpatterns
	$tlsrc->depends
	$tlsrc->executes

Generation function
	$tlp = $tlsrc->make_tlpobj($tltree);
		generates a TeXLive::TLPOBJ object from itself and
		a TeXLive::TLTREE object (see below)


Module TeXLive::TLPOBJ
----------------------

PLEASE SEE THE MANPAGE OF TeXLive::TLPOBJ which is MORE UP 2 DATE!!!!

Package variables:
	&TeXLive::TLPOBJ->zipdir
		set/returns the default location for created zip files

Constructur:
	TeXLive::TLPOBJ->new;
	TeXLive::TLPOBJ->new( name => "foobar", ...);

Input/Output
	$tlp->from_file("package.tlp");
		reads from file, only one tlp allowed in file
	$tlp->from_fh($filehandle [, $multi] );
		reads from $filehandle
		if $multi is undefined (ie not given) then multiple tlp
		in the same file are treated as errors 
		if $multi is defined then returns after reading one
		tlp
		returns 1 if it found a tlp, otherwise 0
	$tlp->writeout
		without arg to stdout
		with arg to filehandle
	$tlp->writeout_simple
		for comparison with tpm/tlps, will go away

	$tlp->make_zip($tltree[,$destdir[,$zipname]]);
		creates a zip file of the arch INDEPENDENT files in tlp 
		in $destdir (if not defined then TLP->zipdir is used).
		The file name of the created zipfile is $zipname (if not
		present $tlp->name.zip)

		If the package contains "binfiles"; then zip files for 
		all archs containing ONLY the binfiles are created, and 
		the zipfile name is
			$zipname.$arch.zip

		All the arch independent zip files ALSO contain the 
		respective TLPOBJ file in 
			.tlpobj/$name.tlpobj
		SO $zipname.zip does contain this tlpobj file, while
		$zipname.$arch.zip does NOT.

		(Compatibility with the scheme used before)
	
	$tlp->update_from_catalogue($texcatalogue);
		merges some information from the TeX Catalogue into 
		the TLPOBJ

Utilities:
	$tlp->recompute_sizes($tltree)
		recomputes all the *size fields, see below
	$tlp->recompute_revision($tltree)
		recomputes the revision of the package
	$tlp->is_arch_dependent
		true if it contains bin files, otherwise false
	$tlp->total_size
		if no arguments given this is 
			srcsize + docsize + runsize
		if args are given then this is
			srcsize + docsize + runsize +
				+ sum_{i in args} binsize{$i}

Read/Write functions (with argument set, without arg read)

	$tlp->name
	$tlp->category
	$tlp->revision
	$tlp->shortdesc
	$tlp->longdesc
	$tlp->catalogue
		reads/returns scalar
	$tlp->srcfiles
	$tlp->srcsize
	$tlp->docfiles
	$tlp->docsize
	$tlp->runfiles
	$tlp->runsize
		*files reads/returns array of files
		*size reads/returns scalar
	$tlp->binfiles
	$tlp->binsize
		note that this gives/returns a HASH of architectures!!
	$tlp->depends
	$tlp->executes
		reads/returns array

	$tlp->add_srcfiles(@files)
	$tlp->remove_srcfiles(@files)
		adds @files to the list of srcfiles
	$tlp->add_docfiles(@files)
	$tlp->remove_docfiles(@files)
		adds @files to the list of docfiles
	$tlp->add_runfiles(@files)
	$tlp->remove_runfiles(@files)
		adds/removes @files to the list of runfiles

	$tlp->add_binfiles($arch,@files)
	$tlp->remove_binfiles($arch,@files)
		adds/removes @files to the list of binfiles for arch=$arch
	
	$tlp->add_files($type,@files)
	$tlp->remove_files($type,@files)
		adds/removes @files to the list of $type = (run|doc|src)files
		NOT FOR binfiles!


Module TeXLive::TLTREE
----------------------
(this one is still quite hacky)

Constructor

	TeXLive::TLTREE->new;
	TeXLive::TLTREE->new( svnroot => "path/to/svn/managed/dir" );

Init functions

	$tltree->init_from_svn
		changes to svnroot, calls svn status -v and builds
		up all the necessary information
	$tltree->init_from_statusfile($file)
		does the same as init_from_svn, but from a pre-made
		output of svn status -v
	$tltree->init_from_files
		inits from a find $svnroot command, all the revisions
		are set to 1

Input/Ouput

	$tltree->print
		to stdout, more or less for hacking only not usefull

Pattern matching functions
	
	$ref = $tltree->get_matching_files($type,$pattern)
		for $type = bin
			returns a ref to a hash of keys = architectures
		otherwise
			returns a ref to an array
		(see specification)

		Note that a pattern of the form
			bin/${ARCH}/foobar
		also matches for arch=win32 
			bin/${ARCH}/foobar.{exe,bat}


Other functions

	$tltree->file_svn_lastrevision($file)
		returns the revision of the last change of file
		as given by svn status -v
		undef if file is not contained in $tltree

	$tltree->size_of($file)
		returns the size of $file, or undef if not in tree

	&$tlsrc->architectures
		sets/reads the list of architectures,
		predefined to ....


Module TeXLive::TLPDB
------------------------
Package variables:
	&TeXLive::TLPDB->listdir
		sets/returns the default location for created list files

Constructor

	TeXLive::TLPDB->new;
	TeXLive::TLPDB->new ( location => "path/to/tldb/file" );
	TeXLive::TLPDB->new ( location => "http://path/to/tldb/file" );
	TeXLive::TLPDB->new ( location => "ftp://path/to/tldb/file" );

Read/Write functions (with argument set, without arg read)

	$tldb->location

Input/Output

	$tldb->from_file("path/to/tldb/file");
	$tldb->from_file("http://path/to/tldb/file");
	$tldb->from_file("ftp://path/to/tldb/file");
		reads a tldb file (tlp descriptions separated by newlines)
	
	$tldb->writeout
		without arg to stdout 
		with arg to filehandle

	$tldb->save
		saves to $self->location;

	$tldb->generate_packagelist
		outputs list of "package revision" for web delivery
		without arg to stdout
		with arg to filehandle

	$tldb->generate_listfiles([$destdir])
		create list file(s) in $destdir (if not given then it defaults
		to TLDB->listdir) (could be more than one for
		packages with binary files)
	
	$tldb->list_packages
		returns all packages installed

TLP interface

	$tldb->add_tlpobj($tlp)
		adds a TeXLive::TLPOBJ to the db (or replaces an already present)

	$tlp = $tldb->get_package("packagename");
		returns undef if not installed
	
	$rev = $tldb->package_revision("packagename");
		returns undef if not installed, otherwise the
		revision of "packagename"
	

Package TeXLive::TLUtils
------------------------

exported functions:
	 platform;
	 platform_desc($platform);
	 win32;
	 unix;
	 getenv($string);
	 which($string);
	 program_exists($program);
	 get_system_tmpdir;
	 dirname($path);
	 basename($path);
	 dirname_and_basename($path);
	 mkdirhier($path);
	 copy($file, $target_dir);
	 media;
	 initialze_installer;
	 binaries_available_from_disk;
	 binaries_available_from_net;
	 make_var_skeleton($path);
	 make_local_skeleton($path);
	 sort_uniq(@list);
	 push_uniq(\@list, @items);
	 member($item, @list);
	 debug($string);