\begin{quote}
A scaffolding library for the modern web. \end{quote}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1217}{}\doxysection{Description}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1217}
Schematics are generators that transform an existing filesystem. They can create files, refactor existing files, or move files around.

What distinguishes Schematics from other generators, such as Yeoman or Yarn Create, is that schematics are purely descriptive; no changes are applied to the actual filesystem until everything is ready to be committed. There is no side effect, by design, in Schematics.\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1218}{}\doxysection{Glossary}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1218}
\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Term   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Term   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
{\bfseries{Schematics}}   &A generator that executes descriptive code without side effects on an existing file system.    \\\cline{1-2}
{\bfseries{Collection}}   &A list of schematics metadata. Schematics can be referred by name inside a collection.    \\\cline{1-2}
{\bfseries{Tool}}   &The code using the Schematics library.    \\\cline{1-2}
{\bfseries{Tree}}   &A staging area for changes, containing the original file system, and a list of changes to apply to it.    \\\cline{1-2}
{\bfseries{Rule}}   &A function that applies actions to a {\ttfamily Tree}. It returns a new {\ttfamily Tree} that will contain all transformations to be applied.    \\\cline{1-2}
{\bfseries{Source}}   &A function that creates an entirely new {\ttfamily Tree} from an empty filesystem. For example, a file source could read files from disk and create a Create Action for each of those.    \\\cline{1-2}
{\bfseries{Action}}   &An atomic operation to be validated and committed to a filesystem or a {\ttfamily Tree}. Actions are created by schematics.    \\\cline{1-2}
{\bfseries{Sink}}   &The final destination of all {\ttfamily Action}s.   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1219}{}\doxysection{Tooling}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1219}
Schematics is a library, and does not work by itself. A \href{https://github.com/angular/angular-cli/blob/master/packages/angular_devkit/schematics_cli/bin/schematics.ts}{\texttt{ reference CLI}} is available on this repository, and is published on NPM at \href{https://www.npmjs.com/package/@angular-devkit/schematics-cli}{\texttt{ @angular-\/devkit/schematics-\/cli}}. This document explains the library usage and the tooling API, but does not go into the tool implementation itself.

The tooling is responsible for the following tasks\+:


\begin{DoxyEnumerate}
\item Create the Schematic Engine, and pass in a Collection and Schematic loader.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Understand and respect the Schematics metadata and dependencies between collections. Schematics can refer to dependencies, and it\textquotesingle{}s the responsibility of the tool to honor those dependencies. The reference CLI uses NPM packages for its collections.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Create the Options object. Options can be anything, but the schematics can specify a JSON Schema that should be respected. The reference CLI, for example, parses the arguments as a JSON object and validates it with the Schema specified by the collection.
\begin{DoxyEnumerate}
\item Schematics provides some JSON Schema formats for validation that tooling should add. These validate paths, html selectors and app names. Please check the reference CLI for how these can be added.
\end{DoxyEnumerate}
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Call the schematics with the original Tree. The tree should represent the initial state of the filesystem. The reference CLI uses the current directory for this.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Create a Sink and commit the result of the schematics to the Sink. Many sinks are provided by the library; File\+System\+Sink and Dry\+Run\+Sink are examples.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Output any logs propagated by the library, including debugging information.
\end{DoxyEnumerate}

The tooling API is composed of the following pieces\+:\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1220}{}\doxysubsection{Engine}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1220}
The {\ttfamily Schematic\+Engine} is responsible for loading and constructing {\ttfamily Collection}s and {\ttfamily Schematics}. When creating an engine, the tooling provides an {\ttfamily Engine\+Host} interface that understands how to create a {\ttfamily Collection\+Description} from a name, and how to create a {\ttfamily Schematic\+Description}.\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1221}{}\doxysection{Schematics (\+Generators)}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1221}
Schematics are generators and part of a {\ttfamily Collection}.\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1222}{}\doxysubsection{Collection}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1222}
A Collection is defined by a {\ttfamily collection.\+json} file (in the reference CLI). This JSON defines the following properties\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{3}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Prop Name   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-3}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Prop Name   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-3}
\endhead
{\bfseries{name}}   &{\ttfamily string}   &The name of the collection.    \\\cline{1-3}
{\bfseries{version}}   &{\ttfamily string}   &Unused field.   \\\cline{1-3}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1223}{}\doxysubsection{Schematic}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1223}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1224}{}\doxysection{Operators, Sources and Rules}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1224}
A {\ttfamily Source} is a generator of a {\ttfamily Tree}; it creates an entirely new root tree from nothing. A {\ttfamily Rule} is a transformation from one {\ttfamily Tree} to another. A {\ttfamily Schematic} (at the root) is a {\ttfamily Rule} that is normally applied on the filesystem.\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1225}{}\doxysubsection{Operators}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1225}
{\ttfamily File\+Operator}s apply changes to a single {\ttfamily File\+Entry} and return a new {\ttfamily File\+Entry}. The result follows these rules\+:


\begin{DoxyEnumerate}
\item If the {\ttfamily File\+Entry} returned is null, a {\ttfamily Delete\+Action} will be added to the action list.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item If the path changed, a {\ttfamily Rename\+Action} will be added to the action list.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item If the content changed, an {\ttfamily Overwrite\+Action} will be added to the action list.
\end{DoxyEnumerate}

It is impossible to create files using a {\ttfamily File\+Operator}.\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1226}{}\doxysubsection{Provided Operators}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1226}
The Schematics library provides multiple {\ttfamily Operator} factories by default that cover basic use cases\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ File\+Operator   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ File\+Operator   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
{\ttfamily content\+Template$<$T$>$(options\+: T)}   &Apply a content template (see the Template section)    \\\cline{1-2}
{\ttfamily path\+Template$<$T$>$(options\+: T)}   &Apply a path template (see the Template section)   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1227}{}\doxysubsection{Provided Sources}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1227}
The Schematics library additionally provides multiple {\ttfamily Source} factories by default\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Source   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Source   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
{\ttfamily empty()}   &Creates a source that returns an empty {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily source(tree\+: Tree)}   &Creates a {\ttfamily Source} that returns the {\ttfamily Tree} passed in as argument.    \\\cline{1-2}
{\ttfamily url(url\+: string)}   &Loads a list of files from the given URL and returns a {\ttfamily Tree} with the files as {\ttfamily Create\+Action} applied to an empty {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily apply(source\+: Source, rules\+: Rule\mbox{[}$\,$\mbox{]})}   &Apply a list of {\ttfamily Rule}s to a source, and return the resulting {\ttfamily Source}.   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1228}{}\doxysubsection{Provided Rules}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1228}
The schematics library also provides {\ttfamily Rule} factories by default\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Rule   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Rule   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
{\ttfamily noop()}   &Returns the input {\ttfamily Tree} as is.    \\\cline{1-2}
{\ttfamily chain(rules\+: Rule\mbox{[}$\,$\mbox{]})}   &Returns a {\ttfamily Rule} that\textquotesingle{}s the concatenation of other {\ttfamily Rule}s.    \\\cline{1-2}
{\ttfamily for\+Each(op\+: File\+Operator)}   &Returns a {\ttfamily Rule} that applies an operator to every file of the input {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily move(root\+: string)}   &Moves all the files from the input to a subdirectory.    \\\cline{1-2}
{\ttfamily merge(other\+: Tree)}   &Merge the input {\ttfamily Tree} with the other {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily content\+Template$<$T$>$(options\+: T)}   &Apply a content template (see the Template section) to the entire {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily path\+Template$<$T$>$(options\+: T)}   &Apply a path template (see the Template section) to the entire {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily template$<$T$>$(options\+: T)}   &Apply both path and content templates (see the Template section) to the entire {\ttfamily Tree}.    \\\cline{1-2}
{\ttfamily filter(predicate\+: File\+Predicate$<$boolean$>$)}   &Returns the input {\ttfamily Tree} with files that do not pass the {\ttfamily File\+Predicate}.   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1229}{}\doxysection{Templating}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1229}
As referenced above, some functions are based upon a file templating system, which consists of path and content templating.

The system operates on placeholders defined inside files or their paths as loaded in the {\ttfamily Tree} and fills these in as defined in the following, using values passed into the {\ttfamily Rule} which applies the templating (i.\+e. {\ttfamily template$<$T$>$(options\+: T)}).\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1230}{}\doxysubsection{Path Templating}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1230}
\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Placeholder   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Placeholder   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
{\bfseries{variable}}   &Replaced with the value of {\ttfamily variable}.    \\\cline{1-2}
\+\_\+\+\_\+variable@function\+\_\+\+\_\+   &Replaced with the result of the call {\ttfamily function(variable)}. Can be chained to the left ({\ttfamily \+\_\+\+\_\+variable@function1@function2\+\_\+\+\_\+} etc).   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1231}{}\doxysubsection{Content Templating}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1231}
\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Placeholder   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Placeholder   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Description    }\\\cline{1-2}
\endhead
$<$\%= expression \%$>$   &Replaced with the result of the call of the given expression. This only supports direct expressions, no structural (for/if/...) Java\+Script.    \\\cline{1-2}
$<$\%-\/ expression \%$>$   &Same as above, but the value of the result will be escaped for HTML when inserted (i.\+e. replacing \textquotesingle{}$<$\textquotesingle{} with \textquotesingle{}$<$\textquotesingle{})    \\\cline{1-2}
$<$\% inline code \%$>$   &Inserts the given code into the template structure, allowing to insert structural Java\+Script.    \\\cline{1-2}
$<$\%\# text \%$>$   &A comment, which gets entirely dropped.   \\\cline{1-2}
\end{longtabu}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1232}{}\doxysection{Examples}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1232}
\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1233}{}\doxysubsection{Simple}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1233}
An example of a simple Schematics which creates a \char`\"{}hello world\char`\"{} file, using an option to determine its path\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{import \{Tree\} from '@angular-\/devkit/schematics';}
\DoxyCodeLine{}
\DoxyCodeLine{export default function MySchematic(options: any) \{}
\DoxyCodeLine{  return (tree: Tree) => \{}
\DoxyCodeLine{    tree.create(options.path + '/hi', 'Hello world!');}
\DoxyCodeLine{    return tree;}
\DoxyCodeLine{  \};}
\DoxyCodeLine{\} }

\end{DoxyCode}


A few things from this example\+:


\begin{DoxyEnumerate}
\item The function receives the list of options from the tooling.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item It returns a \href{src/engine/interface.ts\#L73}{\texttt{ {\ttfamily Rule}}}, which is a transformation from a {\ttfamily Tree} to another {\ttfamily Tree}.
\end{DoxyEnumerate}\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1234}{}\doxysubsection{Templating}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1234}
A simplified example of a Schematics which creates a file containing a new Class, using an option to determine its name\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{// files/\_\_name@dasherize\_\_.ts}
\DoxyCodeLine{}
\DoxyCodeLine{export class <\%= classify(name) \%> \{}
\DoxyCodeLine{\} }

\end{DoxyCode}



\begin{DoxyCode}{0}
\DoxyCodeLine{// index.ts}
\DoxyCodeLine{}
\DoxyCodeLine{import \{ strings \} from '@angular-\/devkit/core';}
\DoxyCodeLine{import \{}
\DoxyCodeLine{  Rule, SchematicContext, SchematicsException, Tree,}
\DoxyCodeLine{  apply, branchAndMerge, mergeWith, template, url,}
\DoxyCodeLine{\} from '@angular-\/devkit/schematics';}
\DoxyCodeLine{import \{ Schema as ClassOptions \} from './schema';}
\DoxyCodeLine{}
\DoxyCodeLine{export default function (options: ClassOptions): Rule \{}
\DoxyCodeLine{  return (tree: Tree, context: SchematicContext) => \{}
\DoxyCodeLine{    if (!options.name) \{}
\DoxyCodeLine{      throw new SchematicsException('Option (name) is required.');}
\DoxyCodeLine{    \}}
\DoxyCodeLine{}
\DoxyCodeLine{    const templateSource = apply(}
\DoxyCodeLine{      url('./files'),}
\DoxyCodeLine{      [}
\DoxyCodeLine{        template(\{}
\DoxyCodeLine{          ...strings,}
\DoxyCodeLine{          ...options,}
\DoxyCodeLine{        \}),}
\DoxyCodeLine{      ]}
\DoxyCodeLine{    );}
\DoxyCodeLine{}
\DoxyCodeLine{    return branchAndMerge(mergeWith(templateSource));}
\DoxyCodeLine{  \};}
\DoxyCodeLine{\} }

\end{DoxyCode}


Additional things from this example\+:
\begin{DoxyEnumerate}
\item {\ttfamily strings} provides the used {\ttfamily dasherize} and {\ttfamily classify} functions, among others.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item The files are on-\/disk in the same root directory as the {\ttfamily index.\+ts} and loaded into a {\ttfamily Tree}.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Then the {\ttfamily template} {\ttfamily Rule} fills in the specified templating placeholders. For this, it only knows about the variables and functions passed to it via the options-\/object.
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Finally, the resulting {\ttfamily Tree}, containing the new file, is merged with the existing files of the project which the Schematic is run on.
\end{DoxyEnumerate}\hypertarget{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1235}{}\doxysection{Future Work}\label{md_sfcode_node_modules__angular_devkit_schematics_README_autotoc_md1235}
Schematics is not done yet. Here\textquotesingle{}s a list of things we are considering\+:


\begin{DoxyItemize}
\item Smart defaults for Options. Having a Java\+Script function for default values based on other default values.
\item Prompt for input options. This should only be prompted for the original schematics, dependencies to other schematics should not trigger another prompting.
\item Tasks for running tooling-\/specific jobs before and after a schematics has been scaffolded. Such tasks can involve initialize git, or npm install. A specific list of tasks should be provided by the tool, with unsupported tasks generating an error. 
\end{DoxyItemize}