Theos

A cross-platform build system for creating iOS, macOS, Linux, and Windows programs.

NIC: Syntax

The New Instance Creator (NIC) is a component of the Theos development suite that allows projects (“instances”) to be created quickly based on 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 their ~/.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 their ~/.nicrc.

  • NIC->setConstraint($constraint)

  • NIC->clearConstraint($constraint)
    • methods
    • Set or clear the constraint given by $constraint.
  • 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";