Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NEWFILE(1)			 CommWare.NET			    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

       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.

       nneewwffiillee is a program for	creating starter files,	or trees of files, by
       processing templates with a C-preprocessor-like syntax.

       FFiinnddiinngg tteemmppllaatteess

       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: "li-
       censes",	"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 di-
       rectory 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 al-
       ways 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 lo-
       cated (by convention) in	the "licenses" subdirectory of each directory
       on the search path.

       For project templates, the naming convention is similar to that for li-
       censes, 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.

	   The name of the template used to construct the current project or

	   The name of the input file, minus any directory prefix.

	   An identifier based on NAME.

	   If a	project	template is being expanded, this is the	name of	the

	   An identifier based on PROJ.

	   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.

	   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.

	   Defined by the command line option "-e/--email". If not given, con-
	   structed from the user's login name and the hostname.

	   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.

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

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

	   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.

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

       NNoottee:: the quotes	around the filename are	required.

       NNoottee:: Relative paths are	evaluated relative to the directory from which
       nneewwffiillee was run.	(nneewwffiillee does not change directory in the course of

       LLiinnee ccoonnttiinnuuaattiioonn

       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.

       PPrreepprroocceessssoorr ddiirreeccttiivveess

       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.

	   Insert the contents of the currently	defined	license	header.	 This
	   is a	file called, e.g., "",	where LTYPE is the li-
	   cense 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".

	   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	"%en-

	   The text up to the matching "%endif"	if used	if the previously
	   tested condition(s) was/were	false.

	   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 in-
	   cluded file to change the interpretation of the enclosing file.

	   NNoottee:: 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 di-

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

	   Sets	the string used	to start preprocessor directives to what it
	   was before the most recent "%metapush".

	   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	ig-
       nored, 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 ggcccc's error messages,
       and shows the included files leading up to the point of the the error.

	   String containing default command line options. Normal shell	quot-
	   ing 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 ex-
	   posed 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 docu-

       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.

3rd Berkeley Distribution	   GEEK	OUT!			    NEWFILE(1)

N | S | D | D | E | F | C | B | R | N | A | H

Want to link to this manual page? Use this URL:

home | help