NEWFILE(1) CommWare.NET NEWFILE(1)NAMEnewfile - create new files from templates
SYNOPSIS
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.
DESCRIPTIONnewfile is a program for creating starter files, or trees of files, by
processing templates with a C-preprocessor-like syntax.
Finding templates
Directory searching
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 appro‐
priate 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.
Naming template files
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 "FILE‐
TYPE" 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 direc‐
tory 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.
Variables
Builtins
Some variables are built into the system, and should always be defined.
Some will get default values if not defined.
TEMPLATE
The name of the template used to construct the current project or
file(s).
NAME
The name of the input file, minus any directory prefix.
NAMEID
An identifier based on NAME.
PROJECT
If a project template is being expanded, this is the name of the
template.
PROJECTID
An identifier based on PROJ.
LICENSE
Defined by the command line option "-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.
AUTHOR
Defined by the command line option "-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.
EMAIL
Defined by the command line option "-e/--email". If not given, con‐
structed from the user's login name and the hostname.
ORGANIZATION
The organization to which the author belongs, in the context of the
code or document being created. If not given, defaults to the value
of AUTHOR.
OWNER
Defined by the command line option "-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".
BODY
If defined, indicates to many templates to include extra boiler‐
plate text to define a skeleton body for the file. See the individ‐
ual templates for details. The shell and ruby templates are espe‐
cially good examples, since these are the languages I've been using
most and these templates have received the most attention to
detail.
c(omment)
The value of a leading string to be prefixed to text in a comment
block. This is handled entirely within the templates themselves.
Getting a variable's value
The syntax <:VARIABLE> will be substituted with the value of the vari‐
able. If the variable does not exist, it will be replaced with the
string "*UNDEFINED*".
Checking if a variable is defined
The special function defined("VARIABLE") can be used in preprocessor
conditionals (the section on "Preprocessor directives") to test if a
variable is defined or not.
Note: the quotes around the variable name are required.
Files
Checking if a file exists
The special function exists("filename") can be used in preprocessor
conditionals (the section on "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.)
Line continuation
Lines used to control the preprocessor (the section on "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.
Preprocessor directives
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.
%define VAR [VALUE]
Define or redefined a variable. One layer of quotes is stripped
from the optional value unless the open quote is preceded by a lit‐
eral backslash ("\"). The default value is "1".
%undef VAR
Undefine a variable, if it is defined.
%license
Insert the contents of the currently defined license header. This
is a file called, e.g., "LTYPE@license.inc", where LTYPE is the
license type, such as BSD or GPL.
%include <file>
Insert the contents of "file" at this point. The file is found by
searching the current search path. Variable substitution is per‐
formed on "file", so "%include <<:BODY>>" will include the file
whose name is in the variable "BODY".
%if COND-EXPRESSION
Test a conditional expression. Expressions are evaluated by the
Ruby interpreter after variable substitution. The text up to the
next matching "%elif", "%else", or "%endif" is used if the expres‐
sion is true.
%elif COND-EXPRESSION
Shorthand for "%else", followed by "%if", but saves an extra
"%endif".
%else
The text up to the matching "%endif" if used if the previously
tested condition(s) was/were false.
%endif
Ends a "%if/%elif/%else" sequence.
%metastr STR
Sets the string used to start preprocessor directives to STR. It is
initially set to "%". 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 confu‐
sion, try to avoid its use wherever possible.
%metapush STR
Sets the string used to start preprocessor directives to STR. It is
initially set to "%". 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.
%metapop
Sets the string used to start preprocessor directives to what it
was before the most recent "%metapush".
%end
Causes the preprocessor to ignore the rest of the file. You can,
e.g., put documentation about the template after a "%end".
All other lines are either copied with variable substitution, or
ignored, depending on the current conditional state.
DIAGNOSTICS
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.
ENVIRONMENT
NEWFILE
String containing default command line options. Normal shell quot‐
ing conventions apply.
FILES
· $HOME/.alane-newfile/*
· $PREFIX/share/alane-newfile/*
CAVEATS
· Does not check before overwriting existing files.
BUGS
· Doesn't always issue good error messages and exit gracefully if bad
input is given. Too much of the Ruby exception mechanism may be
exposed to the user.
RESTRICTIONS
See the BSD License in the file "LICENSE" in the source distribution.
NOTES
There's still room for improvement, but the basic engine is solid. What
is needed now are more templates, and getting all the templates docu‐
mented.
A command line option to fetch template documentation after a %end
would be really nice, too.
AUTHOR
AlanE@geeksrus.net
HISTORY
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.
3rd Berkeley Distribution GEEK OUT! NEWFILE(1)
