newfile - create new files from templates
This man page documents newfile v. 1.0.13.
This is newfile v. 1.0.11. Release: ``Plastic leather, 13DDD''
Copyright (c) 2002-2003 Alan Eldridge <alane@geeksrus.net>. All rights reserved.
usage: newfile -h
newfile -V
newfile [options] -s|--show
newfile [options] -D<project>
newfile [options] -d<template>
newfile [options] -t<template> <file> ...
newfile [options] -p<template>.<projectname> [<dir>]
(note: <dir> defaults to <projectname> if omitted)
-h, --help Show this help.
-V, --version Show version and copyright.
-v, --verbose Turn on verbose messages.
-l, --license=LICENSE Set license type.
-t, --filetype=TEMPLATE Set file TEMPLATE to use.
Do *not* use with -p/--project.
-p=TEMPLATE.PROJECTNAME Set project TEMPLATE to use, and
PROJECTNAME of project being built.
Do *not* use with -t/--filetype.
--project
-s, --show Show installed file templates, project
templates, and license types.
-P, --pdoc=PROJECT Show embedded docs for PROJECT.
-T, --doc=TEMPLATE Show embedded docs for TEMPLATE.
-x, --exec-bit Make the resulting file executable.
This option has no effect if a project
template is selected.
-a, --author=AUTHOR Set name of author.
-e, --email=EMAIL Set author's email address.
-o, --organization=ORGANIZATION Set author's organization name.
-c, --owner=COPYRIGHT_OWNER Set copyright owner's name.
-I, --include=DIR Add DIR to search path.
-D, --define=VAR[=value] Define a variable. Value defaults to 1.
newfile is a program for creating starter files, or trees of files, by processing templates with a C-preprocessor-like syntax.
Templates and projects (file tree templates) are found by looking in
the search path for a directory containing the template file(s).
For each directory in the search path, three subdirs are searched:
licenses, projects, and templates.
The user can create a directory hierarchy $HOME/.newfile in which
to place new or modified templates and projects. This directory
is searched before the system include directory. It should
have the appropriate subdirectories for licenses, projects, and/or
templates, just like the system include directory.
Other search directories can be added with the -I/--include command line
option. They will be searched before either the user's include directory
or the system include directory, in the reverse order from that given on
the command line.
Unlike older versions of this program, template subdirectories are always
just 1 level deep. That is, e.g., the templates subdirectory will not
have any subdirectories of its own. This simplifies the searching process
immensely; in return, files must be named according to specific rules.
For file templates, the name should be tmpl@FILETYPE, where FILETYPE
is the value given to the -t/--template command line option. E.g., the
template for ruby files (-t rb) is tmpl@rb. These files are all located
in the templates subdirectory of each directory on the search path.
For license templates, the name should be LTYPE@REALNAME, where LTYPE
is the value given to the -l/--license command line option, and
REALNAME is the actual name of the file. These files are all located
(by convention) in the licenses subdirectory of each directory on the
search path.
For project templates, the naming convention is similar to that for
licenses, with the added feature that a ``!'' in the filename indicates
a ``/'' in the final directory name. This is how subdirectories in the
project are specified. E.g., auto@src!Makefile.am means the file
Makefile.am in the src subdirectory of the project directory. These
files are all located (by convention) in the projects subdirectory
of each directory on the search path.
Some variables are built into the system, and should always be defined. Some will get default values if not defined.
-l/--license. Licenses are a special
case of project templates, and their files are mixed in with a project
template's file. In the case of a single file, the value of LICENSE
determines which directory to search for a file called ``license'' that is
included in the generated file.
-a/--author. The name of the author
of the code or document. If not given, taken from the user's full name in
the /etc/passwd file.
-e/--email. If not given, constructed
from the user's login name and the hostname.
-o/--owner. The owner of the
copyright. May be an arbitrary string, or one of the special strings ``org'',
``organization'', or ``author''. If not given, defaults to ``author''.
c(omment)
The syntax <:VARIABLE> will be substituted with the value of the variable. If the variable does not exist, it will be replaced with the string ``*UNDEFINED*''.
The special function defined(``VARIABLE'') can be used in preprocessor conditionals (Preprocessor directives) to test if a variable is defined or not.
Note: the quotes around the variable name are required.
The special function exists(``filename'') can be used in preprocessor conditionals (Preprocessor directives) to test if a variable is defined or not.
Note: the quotes around the filename are required.
Note: Relative paths are evaluated relative to the directory from which newfile was run. (newfile does not change directory in the course of execution.)
Lines used to control the preprocessor (Preprocessor directives) may be continued by ending the line with the characters ``%+''. No spaces may appear after these characters in order for the line to be continued.
The pre-processor supports a set of directives very similar to the C preprocessor. The leading character for all directives in ``%'', and must occur in the first column of the line.
LTYPE@license.inc, where LTYPE is the
license type, such as BSD or GPL.
%include <<:BODY>> will include the
file whose name is in the variable BODY.
%elif, %else, or %endif is used if the expression is true.
%else, followed by %if, but saves an extra %endif.
%endif if used if the previously tested
condition(s) was/were false.
%if/%elif/%else sequence.
%. This directive remains in effect only until the
end of the file in which it occurs. It cannot be used in an
included file to change the interpretation of the enclosing file.
Note: If the template needs to include a license file, it would be a good idea to wait until after that is done before using this directive.
Note: This directive was added specifically to allow creation of
MagicPoint templates, which have a %if statement. To avoid confusion,
try to avoid its use wherever possible.
%. This directive remains in effect only until the
?metapop directive is encountered. All %metapush directives are
undone at the end of the file in which they were found.
%metapush.
%end.
All other lines are either copied with variable substitution, or ignored, depending on the current conditional state.
The preprocessor attempts to issue error messages that are as accurate as possible. Each error message is formatted like gcc's error messages, and shows the included files leading up to the point of the the error.
See the BSD License in the file ``LICENSE'' in the source distribution.
There's still room for improvement, but the basic engine is solid. What is needed now are more templates, and getting all the templates documented.
A command line option to fetch template documentation after a %end would be really nice, too.
This is the third rendition of this program, written first in shell, then in Python, and finally in ruby. In this case, I think ruby allows easier transition from intent to code than Python.