Note: This is work in progress and subject to breaking changes.
Knit parses knitting patterns into a parse tree.
To make this work reliably, we define a simple and relatively strict pattern syntax. There are established knitting pattern formats out there, but they are not strict enough to be suitable for parsing in a practical and efficient manner.
The pattern constructs we do support are taken from the overview on craftyarncouncil.com.
The lowest syntax level concerns the actual pattern constructs we recognize and these are only a small handful of minimal components we need to build everything else (see below). All constructs are case insensitive.
A single pattern can define stitch sequences for multiple rows.
A row can be denoted with the
Row keyword. It can optionally be
followed by a number, indicating which row this represents.
Any pattern data following this Row node, up until the end of the pattern, or the next Row node, should be considered part of the same row. For example:
Row 1: P10 K10 P10 Row 2: K10 P10 K10
This pattern defines the stitching sequences for two distinct rows.
K: Knit stitch
P: Purl stitch
Ks: Knitwise Slip stitch
Ps: Purlwise Slip stitch
Yo: Yarn over
K4Tog: Knit N together.
P4Tog: Purl N together.
Ca: Single Cable stitch
Psso: Pass second to last sitch over last one.
Stitches can be directly followed by a quantifier (see below), in order
to determine how often they should be repeated. For example
P3 K2 means:
Three Purl stitches, followed by two Knit stitches.
Stitches can be prefixed with a modifier (see below). These specify some special
usecase for the particular stitch. For example
@P2 @K3 means: Two Purl
stitches through back loop, followed by three Knit stitches through back loop.
Any sequence of stitches can be encased in
], to turn it into a
distinct grouping. A group can have its own quantifiers (see below), to
determine how often it should be repeated.
[p3 k3] 10 means: Three Purl stitches, followed by three
knit stitches. And repeat the whole block ten times.
Quantifiers specify the repetition count for a given stitch or group.
They consist of absolute numbers (
2, etc) and specify an absolute
number of repetitions for the preceeding stitch or group.
Every stitch and group has an implicit quantifier of
There is therefore no need to specify it in the pattern if all you need is
for it to be knitted once.
PK means one Purl Stitch, followed by one Knit stitch.
It is functionally identical to the pattern
Modifiers specify unique attributes for a given stitch. These are tokens which directly preceed the stitch name. Multiple modifiers can be applied to a single stitch.
Known modifiers include:
@: Denotes that the stitch is to be worked through the back loop instead of the front loop.
^: Knit deep (previous row).
>: Yarn Forward. Meaning, we pass the working yarn to the front of the work, like one would do for a normal Purl stitch.
<: Yarn backward. Meaning, we pass the working yarn to the back of the work, like one would do for a normal Knit stitch.
@P2 ^K3 means: Two Purl stitches through back loop, followed by
three deep Knit stitches.
In addition, we allow other patterns to be referenced by name. This allow us to split large patterns up into smaller, managable chunks and build more complex patterns by embedding the ready-made building blocks.
For example, pattern 'abc' is defined as
[P3 K3] 5.
Pattern 'xyz' can incorporate 'abc' by referencing it by name:
P10 abc 2 P10.
The parser does not expand the reference to 'abc' during parsing, but it
is left in there as a
Reference node with the name
abc. It is up to the
host application to supply the actual contents of this reference during use.
Alternatively, one can instruct the pattern to do so by calling the
The host application must implement the
ReferenceHandler and it should
return a valid, compiled pattern for the supplied reference name.
Expand expands all references in place.
a, err := Parse("abc", "[P3 K3] 5") b, err := Parse("xyz", "P10 abc 2 P10") err := b.Expand(...)
'xyz' is now:
P10 [[P3 K3] 5] 2 P10
The parser does not do loop unrolling by default. However, it can be
instructed to do so by calling the
P2 K3 [P INC 2] 2
P P K K K P INC INC P INC INC
This is mostly practical when using the pattern to generate some other form of output. Getting rid of the nested groupings like this makes processing considerably easier.
After a call to
Pattern.Unroll, there should be no Number or Group nodes
left in the pattern. Only a flat list of Stitch nodes and optionally some
Reference nodes if
Pattern.Expand was not yet called.
go get github.com/jteeuwen/knit
Unless otherwise stated, all of the work in this project is subject to a 1-clause BSD license. Its contents can be found in the enclosed LICENSE file.