Redesign $realpath #21
Description
[was a comment on #18].
I'm getting used to how Nancy works, and I have some observations about $realpath.
Observations
If the expansion of $realpath appears in an output file it is always wrong, because it expands differently depending on the directory from which Nancy is run. The only sensible use of $realpath is as an argument to a command that will read some property of the file.
Furthermore, if the command merely reads the file contents, then that often does not constitute a sensible use of $realpath, because it would be better (more flexible, less likely to go wrong) to pass the file contents on stdin using Nancy's {...} syntax.
This leaves a significant number of sensible uses, e.g.:
- reading the modification time of the file
- reading the name or type of the file
- finding another file in the same directory as the file
- listing other files in the parent directory of the file
A command which accesses the filename relative to $realpath will only see one of the directories in Nancy's INPUT-TREE argument: the one containing the file being expanded. If more than one tree is passed to Nancy, the others will be hidden. This potentially confusing behaviour is unique to $realpath.
A command which finds another file in the same directory as $realpath bypasses Nancy's inheritance mechanism. For example, if template.in.html refers to $run(dirname,$realpath)}/body.in.md it will only work if body.in.md is in the same directory as template.in.html, and in the same source tree. Here "work" means it computes the filename of the file that would be included by $include(body.in.md).
Suggestions
Because $realpath is significantly difficult to use correctly, it would be nice to find ways of avoiding it. I can't see how in general, but I have a few ideas in particular cases.
Maybe make $realpath into an environment variable NANCY_FILENAME. This would make it available to scripts without using a command-line argument, while making it unavailable in output files, where it makes no sense.
Maybe replace $realpath with $tree/$path, where $tree is the filename of the tree containing the file being expanded. Then, $tree would be the only command whose expansion depends on the directory from which Nancy is run. The documentation of $tree would be explicitly about source trees, which I think would make it clear that its expansion is not something you want to see in an output file. Also, the relationship of $realpath to $path would be clearer.
Maybe cd $tree before $running a command, so that $realpath is equal to $path.
Maybe replace $path with $parent/$name. Several existing scripts take $path as an argument and immediately find its parent. This would only be a small win, however.
A command $filename(name) could be defined to be the filename of the file that Nancy would expand to satisfy $include(name). This would avoid several uses of $run(dirname,$realpath) and also fix Nancy's inheritance mechanism in these cases. $filename without arguments could replace $realpath. However, this fights with some of my other suggestions.
Maybe make $realpath an absolute filename, like $outputpath. Incidentally, the latter should perhaps be a relative filename, I think.