Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  NEWFILE (1)


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 <>. 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.
    -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.

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 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.

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 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! means the file 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.
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, constructed 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 boilerplate text to define a skeleton body for the file. See the individual templates for details. The shell and ruby templates are especially 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 variable. 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.


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 literal 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.,, 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 performed 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 expression 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 confusion, 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.


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.


NEWFILE String containing default command line options. Normal shell quoting conventions apply.


o $HOME/.alane-newfile/*
o $PREFIX/share/alane-newfile/*


o Does not check before overwriting existing files.


o 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.


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.
Search for    or go to Top of page |  Section 1 |  Main Index

Mar 2003 NEWFILE (1) GEEK OUT!

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.