--- /dev/null
+#!/usr/bin/env perl
+
+# lns -- create a symbolic link. Alternative to "ln -s".
+# This program works more like "cp", in that the source path name is not
+# taken literally.
+# ln -s filename /tmp
+# creates a link
+# /tmp/filename -> filename
+# whereas we would prefer
+# /tmp/filename -> /home/me/filename
+# or wherever the file *really* was.
+#
+# Usage: lns [-afF] file1 file2
+# or lns [-af] file1 [file2...] dir
+#
+# Where:
+# -a means absolute - "symlink /usr/bin/argh /usr/local/bin/argh" produces
+# a relative link "/usr/bin/argh -> ../local/bin/argh", but using the
+# -a option will give a real absolute link.
+# -f means forceful - overwrite the target filename if it exists *and* is
+# a link. You can't accidentally overwrite real files like this.
+# -q means quiet - don't complain if we fail to do the job.
+# -v means verbose - say what we're doing.
+# -F means FILE - forces interpretation to be the "file1 file2" syntax,
+# even if file2 is a link to a directory. This option implies -f.
+
+use Cwd;
+
+$usage =
+ "usage: lns [flags] srcfile destfile\n".
+ " or: lns [flags] srcfile [srcfile...] destdir\n".
+ "where: -a create symlinks with absolute path names\n".
+ " -f overwrite existing symlink at target location\n".
+ " -F like -f, but works even if target is link to dir\n".
+ " -v verbosely log activity (repeat for more verbosity)\n".
+ " -q suppress error messages on failure\n".
+ " also: lns --version report version number\n" .
+ " lns --help display this help text\n" .
+ " lns --licence display (MIT) licence text\n";
+
+$licence =
+ "lns is copyright 1999,2004 Simon Tatham.\n" .
+ "\n" .
+ "Permission is hereby granted, free of charge, to any person\n" .
+ "obtaining a copy of this software and associated documentation files\n" .
+ "(the \"Software\"), to deal in the Software without restriction,\n" .
+ "including without limitation the rights to use, copy, modify, merge,\n" .
+ "publish, distribute, sublicense, and/or sell copies of the Software,\n" .
+ "and to permit persons to whom the Software is furnished to do so,\n" .
+ "subject to the following conditions:\n" .
+ "\n" .
+ "The above copyright notice and this permission notice shall be\n" .
+ "included in all copies or substantial portions of the Software.\n" .
+ "\n" .
+ "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n" .
+ "EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n" .
+ "MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n" .
+ "NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\n" .
+ "BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\n" .
+ "ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n" .
+ "CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n" .
+ "SOFTWARE.\n";
+
+$abs=$force=$quiet=$verbose=$FILE=0;
+while ($_=shift @ARGV) {
+ last if /^--$/;
+ unshift (@ARGV, $_), last unless /^-(.*)/;
+ if ($1 eq "-help") {
+ print STDERR $usage;
+ exit 0;
+ } elsif ($1 eq "-version") {
+ if ('$Revision$' =~ /Revision:\s+(\d+)/) {
+ print "lns revision $1\n";
+ } else {
+ print "lns: unknown revision\n";
+ }
+ exit 0;
+ } elsif ($1 eq "-licence" or $1 eq "-license") {
+ print $licence;
+ exit 0;
+ } else {
+ foreach $opt (split //, $1) {
+ if ($opt eq "a") { $abs=1; }
+ elsif ($opt eq "f") { $force=1; }
+ elsif ($opt eq "q") { $quiet=1; }
+ elsif ($opt eq "v") { $verbose++; }
+ elsif ($opt eq "F") { $force=$FILE=1; }
+ else { die "$0: unrecognised option '-$1'\n"; }
+ }
+ }
+}
+
+die $usage if $#ARGV < 1;
+
+die "$0: multiple source files specified with -F option\n"
+ if $#ARGV > 1 && $FILE;
+die "$0: -q (quiet) and -v (verbose) options both specified\n"
+ if $quiet && $verbose;
+
+$target = pop @ARGV;
+die "$0: multiple source files specified, $target not a directory\n"
+ if $#ARGV > 0 && !-d $target;
+
+$multiple = (-d $target && !$FILE);
+$whereami = getcwd();
+
+$target =~ s/// if $target =~ /\/$/; # strip trailing slash if present
+
+if ($multiple) {
+ foreach $source (@ARGV) {
+ $source =~ /^(.*\/)?([^\/]*)$/; # find final file name component
+ &makelink($source, "$target/$2"); # actually make a link
+ }
+} else {
+ $source = $ARGV[0]; # only one source file
+ &makelink($source, $target); # make the link
+}
+
+sub makelink {
+ local ($source, $target) = @_;
+
+ # If the target exists...
+ if (-e $target || readlink $target) {
+ # If it's a symlink and we're in Force mode, remove it and carry on.
+ if ($force && readlink $target) {
+ unlink $target || die "$0: unable to remove link $target\n";
+ # Report that if in Verbose mode.
+ warn "$0: removing existing target link $target\n" if $verbose;
+ } else {
+ # Otherwise, fail. Report that fact if not in Quiet mode.
+ warn "$0: failed to link $source to $target: target exists\n"
+ if !$quiet;
+ return;
+ }
+ }
+
+ # OK, now we're ready to do the link. Calculate the absolute path names
+ # of both source and target.
+ $source = &absolute($source);
+ $target = &absolute($target);
+
+ # If we're in Relative mode (the default), calculate the relative path
+ # name we will reference the source by.
+ $sourcename = $abs ? $source : &relname($source, $target);
+
+ warn "$0: linking $source: $target -> $sourcename\n" if $verbose;
+
+ # Make the link
+ symlink($sourcename, $target) || die "$0: unable to make link to $target\n";
+}
+
+sub absolute {
+ local ($_) = @_;
+ $_ = "$whereami/$_" if !/^\//;
+ s//$whereami/ if /^\./;
+ 1 while s/\/\.\//\//;
+ 1 while s/\/\//\//;
+ 1 while s/\/[^\/]+\/\.\.//;
+ 1 while s/^\/\.\.\//\//;
+ $_;
+}
+
+sub relname {
+ local ($source, $target) = @_;
+ local $prefix;
+
+ # Strip the last word off the target (the actual file name) to
+ # obtain the target _directory_.
+ $target =~ s/\/[^\/]*$//;
+
+ # Our starting prefix is empty. We will add one "../" at a time
+ # until we find a match.
+
+ while (1) {
+
+ # If $target is a prefix of $source, we are done. (No matter what
+ # symlinks may exist on the shared common pathname, if we are
+ # linking `a/b/c/foo' to `foo' then a simple relative link will
+ # work.)
+ if (substr($source, 0, length $target) eq $target) {
+ return $prefix . substr($source, 1 + length $target); # skip the slash
+ }
+
+ # Otherwise, descend to "..".
+
+ $target = $target . "/..";
+
+ # Now normalise the path by removing all ".." segments. We want
+ # to do this while _as far as possible_ preserving symlinks. So
+ # the algorithm is:
+ #
+ # - Repeatedly search for the rightmost `directory/..'
+ # fragment.
+ # - When we find it, one of two cases apply.
+ # * If the directory before the .. is not a symlink, we can
+ # remove both it and the .. from the string.
+ # * If it _is_ a symlink, we substitute it for its link
+ # text, and loop round again.
+ while ($target =~
+ /^(.*)\/((\.|\.\.[^\/]+|\.?[^\/\.][^\/]*)\/\.\.)(\/.*)?$/)
+ {
+ my ($pre, $dir, $frag, $post) = ($1,$2,$3,$4);
+ my $log = "transforming $target -> ";
+ if (-l "$pre/$frag") {
+ my $linktext = readlink "$pre/$frag";
+ if ($linktext =~ /^\//) { # absolute link
+ $target = $linktext;
+ } else { # relative link
+ $target = "$pre/$linktext";
+ }
+ $target .= "/.." . $post;
+ } else {
+ $target = $pre . $post;
+ }
+ $target = "/" if $target eq ""; # special case
+ $log .= "$target";
+ warn "$0: $log\n" if $verbose > 1;
+ }
+
+ # Now we have replaced $target with a pathname equivalent to
+ # `$target/..'. So add a "../" to $prefix, and try matching
+ # again.
+ $prefix .= "../";
+ }
+}
--- /dev/null
+\cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}
+
+\title Man page for \cw{lns}
+
+\U NAME
+
+\cw{lns} - symbolic link creation utility
+
+\U SYNOPSIS
+
+\c lns [ flags ] srcfile destfile
+\e bbb iiiii iiiiiii iiiiiiii
+\c lns [ flags ] srcfile [srcfile...] destdir
+\e bbb iiiii iiiiiii iiiiiii iiiiiii
+
+\U DESCRIPTION
+
+\cw{lns} creates symbolic links.
+
+The standard command \cw{ln -s} also does this, but it interprets
+its first argument as the literal text to be placed in the symlink.
+If your current working directory is not the same as the target
+directory, this can get confusing. For example, to create a symlink
+to a file \cw{hello.c} in a subdirectory \cw{programs}, you would
+have to write \c{ln -s ../hello.c programs}, even though
+\cw{hello.c} is actually in your current directory, not one level
+up. In particular, this is unhelpful because it makes it difficult
+to use tab completion to set up the command line.
+
+\cw{lns} solves this problem, by creating symlinks using the obvious
+semantics you would expect from \cw{mv} or \cw{cp}. All of its
+arguments are expected to be either absolute path names, or relative
+to the \e{current} working directory. So, in the above example, you
+would write \c{lns hello.c programs/hello.c} or just \c{lns hello.c
+programs}, exactly as you would have done if the command had been
+\cw{cp}; and \cw{lns} will figure out for itself that the literal
+text of the symlink needs to be \c{../hello.c}.
+
+\U ARGUMENTS
+
+If you provide precisely two arguments to \cw{lns}, and the second
+one is not a directory (or a symlink to a directory), then \cw{lns}
+will interpret the second argument as a destination file name, and
+create its target link with precisely that name.
+
+If the second argument is a directory, \cw{lns} will assume you want
+a link created \e{inside} that directory, with the same filename as
+the source file. If you supply more than two arguments, \cw{lns}
+will \e{expect} the final argument to a directory, and will do this
+for each of the other arguments.
+
+(This behaviour is intended to mimic \cw{cp} as closely as
+possible.)
+
+The source file(s) are not required to exist. \cw{lns} will create
+links to their locations whether they actually exist or not; if you
+create them later, the links will point to them.
+
+\U OPTIONS
+
+\dt \cw{-a}
+
+\dd Create symlinks with absolute path names (beginning with a
+slash). Normally, \cw{lns} will create relative symlinks. Relative
+symlinks are often more useful: if a parent directory of both the
+link and its target is moved to a new location, a relative symlink
+will still work while an absolute one will fail.
+
+\dt \cw{-f}
+
+\dd Overwrite an existing symlink at the target location. Normally,
+\cw{lns} will warn and refuse to do anything if the target location
+is already occupied by a symlink to a file; using \cw{-f} will cause
+it to replace the existing link with its new one.
+
+\lcont{
+
+If the target location is occupied by something that is \e{not} a
+symlink, \cw{lns} will refuse to overwrite it no matter what options
+you supply.
+
+If you specify precisely two arguments, and the second is a symlink
+to a directory, \cw{lns} will treat it as a destination directory
+rather than a destination file, even if \cw{-f} is specified. Use
+\cw{-F}, described next, to override this.
+
+}
+
+\dt \cw{-F}
+
+\dd Like \cw{-f}, but additionally forces \cw{lns} to interpret its
+second argument as a destination \e{file} name rather than a
+destination directory. This option is useful for overriding an
+existing link to one directory with a link to a different one.
+
+\dt \cw{-v}
+
+\dd Verbose mode: makes \cw{lns} talk about what it is doing. You
+can make it more verbose by adding a second instance of \cw{-v}.
+
+\dt \cw{-q}
+
+\dd Quiet mode: prevents \cw{lns} from printing an error message if
+the link target already exists.
+
+\U EXAMPLES
+
+In simple situations, \cw{lns} can be used pretty much as you would
+use \cw{cp}. For example, suppose you start in directory \cw{dir}
+and issue the following commands:
+
+\c $ lns file1 subdir
+\e bbbbbbbbbbbbbbbb
+\c $ lns file2 ..
+\e bbbbbbbbbbbb
+\c $ lns subdir/file3 subdir2/subsubdir
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+\c $ lns subdir2/file4 subdir2/subsubdir
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+
+Assuming all the subdirectories mentioned actually exist, this will
+create the following symlinks:
+
+\b \cw{subdir/file1}, with link text \cq{../file1}.
+
+\b \cw{../file2}, with link text \cq{dir/file2}.
+
+\b \cw{subdir2/subsubdir/file3}, with link text
+\cq{../../subdir/file3}.
+
+\b \cw{subdir3/subsubdir/file4}, with link text \cq{../file4}.
+
+Note that in each case \cw{lns} has constructed the \e{shortest}
+relative link it could manage: it did not mindlessly create the
+fourth link with text \cq{../../subdir/file4}.
+
+You can specify a target file name instead of a target directory.
+For example, the following command has the same effect as the first
+of the list above:
+
+\c $ lns file1 subdir/file1
+\e bbbbbbbbbbbbbbbbbbbbbb
+
+Now suppose there is another file called \cw{file1} in \cw{subdir2},
+and you want to change the link in \cw{subdir} to point to that.
+Normally \cw{lns} will give you an error:
+
+\c $ lns subdir2/file1 subdir
+\e bbbbbbbbbbbbbbbbbbbbbbbb
+\c lns: failed to link subdir2/file1 to subdir/file1: target exists
+
+You can override this error by using \cw{-f}:
+
+\c $ lns -f subdir2/file1 subdir
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbb
+
+This will overwrite the existing link \cw{subdir/file1} with a new
+one whose text reads \cq{../subdir2/file1}.
+
+Now let's create some symlinks to \e{directories}. Again, this is
+simple to begin with:
+
+\c $ lns subdir2 subdir3
+\c bbbbbbbbbbbbbbbbbbb
+
+This creates a symlink called \cw{subdir3} with text \cq{subdir2}.
+
+In order to overwrite this directory, the \cw{-F} option is likely
+to be useful. Suppose I now want the link \cw{subdir3} to point at
+\cw{subdir} instead of \cw{subdir2}. If I do this:
+
+\c $ lns -f subdir subdir3
+\c bbbbbbbbbbbbbbbbbbbbb
+
+then \cw{lns} will immediately notice that the second argument
+\cw{subdir3} is (a symlink to) a directory, and will therefore
+assume that it was intended to be the directory \e{containing} the
+new link. So it will create a file \cw{subdir3/subdir} (equivalent
+to \cw{subdir/subdir}, of course, since \cw{subdir3} is currently a
+symlink to \cw{subdir}) with link text \cw{../subdir}.
+
+In order to overwrite the directory symlink correctly, you need the
+\cw{-F} option:
+
+\c $ lns -F subdir subdir3
+\c bbbbbbbbbbbbbbbbbbbbb
+
+\cw{-F} tells \cw{lns} that you really want the new symlink to be
+\e{called} \cw{subdir3}, not to be \e{in the directory}
+\cw{subdir3}; and it also implies the \cw{-f} option to force
+overwriting. So now you get what you wanted: the previous symlink
+\cw{subdir3} is replaced with one whose link text reads \cq{subdir}.
+
+\U LICENCE
+
+\cw{lns} is free software, distributed under the MIT licence. Type
+\cw{lns --licence} to see the full licence text.
+
+\versionid $Id$
~mdw / sgt / utils / commitdiff