NIC 2 - Templates

A NIC template is a collection of files representing a basic project, before any user customizations have been added.

Terms and Semantics

Constraint
a condition under a which a file, directory or symlink will be created. A file is said to be constrained when given a condition.
required
The item indicated by this tag must be present.
optional
The item indicated by this tag is optional.
text
The text indicated by text is required to be part of the directive and is not to be substituted with any other values.
...
The tokens preceding the ... may be optionally repeated with the specified delimiter.

Package Control Data (NIC/control)

Each NIC template requires a control file. The control file contains basic static information about the template.

Directives

name "name"
required
Specifies the name of this NIC template.
prompt variable "prompt text" "default value"
optional
Prompts the user for additional information, which will be stored in variable.
Optionally supports the inclusion of a default value, which the user can accept by entering nothing.
The user is given a chance to override the prompt variable with his or her ~/.nicrc.
constrain "path" to constraint
optional
Constrains the given file, directory or symbolic link path to be created only when the constraint condition is met.
ignore built-in variable
optional
Do not prompt for the given built-in variable. The following built-in variables are supported:
  • USER
  • PACKAGENAME

Built-in Constraints

package
Set by default when the new project is expected to be made into a package. Its converse, !package, can be used to create files only when the project is not being packaged.
The NIC templates that ship with Theos use the package constraint to avoid creating unnecessary control files.
link_theos
Used in some templates to include an optional link to theos. Set/overridden by link_theos in the user's ~/.nicrc.
The NIC templates that ship with Theos use this constraint to avoid creating unnecessary theos/ symlinks.

Example NIC/control

name "Awesome Template"
constrain "control" to package
prompt PIES "Number of Pies to create" "10"

Package Control Script (NIC/control.pl)

The package control script is an optional addition to the NIC format.
Control scripts are written in Perl and have access to the current template.

API

There are various objects available to you via the NIC scripting interface.

Public Methods

  • print $data
    method
    Display information to the user.
  • warn $warning
    method
    Display a warning.
  • error $error
    method
    Display an error and abort building the template.
  • exit $status_code
    method
    Exit the control script. Any status code other than 1 will abort building the template.
  • prompt($prompt_text , {default => $default_value})
    method
    Prompt the user for additional information. The default value is optional. Returns the user's response.

NIC

The NIC object represents the current template.

Metadata Manipulation
  • NIC->name
    read/write
    The name of the current template.
  • NIC->variables
    read-only
    A list of the variables currently set on this template.
  • NIC->variable($name)
    read/write
    The value of the named variable. Can be used as a left-hand value, such as in NIC->variable("NAME") = "Value";
  • NIC->prompt($variable, $prompt_text , {default => $default_value})
    method
    Prompt the user for additional information, attaching the user's response to the provided NIC variable. The default value is optional. If $variable is not specified, NIC->prompt(...) will return the user's response, and will not store it in the template.
    The key difference between prompt(...) and NIC->prompt(...) is that the user is given a chance to override the prompt variable with his or her ~/.nicrc.
  • NIC->setConstraint($constraint)
    NIC->clearConstraint($constraint)
    methods
    Set or clear the constraint given by $constraint.
Files, Directories, and Symbolic Links
  • NIC->lookup($name)
    method
    Find an existing File, Directory or Symbolic Link in the template archive.
    Returns the retrieved NICType or undef on failure.
  • NIC->mkfile($name , $mode)
    method
    Create a new File with the given name and, optionally, mode.
    Returns the newly-created File object.
  • NIC->mkdir($name , $mode)
    method
    Create a new Directory with the given name and, optionally, mode.
    Returns the newly-created Directory object.
  • NIC->symlink($target, $destination)
    method
    Create a new Symbolic Link with the given name pointing to the given target.
    $target is expected to be an object acquired via NIC->lookup, NIC->mkdir, NIC->mkfile, or NIC->symlink.
    $target can also be a string.
    Returns the newly-created Symlink object.

NICType

NICType objects are the embodiment of template content. Each file, directory or symbolic link is represented by an instance of a NICType subclass. NICType objects share a few common propeties.

  • $nictype->name
    read/write
    The name of the given NICType object (filename, directory, symbolic link name).
  • $nictype->mode
    read/write
    The mode of the given NICType object. Defaults to 0644 for files and 0755 for directories.
  • $nictype->constraints
    read-only
    A list of the constraints currently attached to the given object.
  • $nictype->constrain($constraint)
    method
    Apply the given constraint to this object. Similar to NIC/control's constrain ....

File <- NICType

Represents a file in the template.

  • $file->data
    read/write
    The file's data.

Directory <- NICType

Represents a directory in the template.
Contains no additional methods.

Symlink <- NICType

Represents a symbolic link in the template.

  • $symlink->target
    read/write
    The target of the symbolic link, as either a reference to a NICType object or a string.

Example NIC/control.pl

# Retrieve the package name as specified by the user.
my $packageName = NIC->variable("PACKAGENAME");
my $packageDirectory = $packageName;

# Transform the package name into a package directory, replacing . with / (s!old!new!g acts as a search and replace).
$packageDirectory =~ s!\.!/!g;

# Create a new directory entry with the name we just transformed.
my $directory = NIC->mkdir($packageDirectory);

# Look up the file "main.m" and set its name to include the new path.
NIC->lookup("main.m")->name = $directory->name . "/main.m";