knitnuggets

A common thing to do in a knitting pattern is to define a stitch pattern “my-cool-stitches” up at the top and then, in the directions, say “k1, my-cool-stitches, blah blah” or “k1, knit the next row of the my-cool-stitches chart, blah blah.” That is the kind of result we are going to end up with in this chapter.

When you are writing a pattern, you can either think in advance about the things that you want to encapsulate up top, or you can write a pattern line by line, then go back and “refactor” to pull things out of the main part of the pattern and into the top part. (Which things? When you’re not sure, one possible approach is “use before reuse” – this means you use something once *before* you worry about making it general enough to reuse. Then when you turn out to need it a second time, refactor to make it reusable; update your first pattern and make sure it still renders ok after the refactoring; then go on to that second pattern.)

How can we refactor in KnitML to separate last chapter’s scarf into a definition of a feather-and-fan stitch pattern plus directions for a “do the next row of the stitch pattern” scarf? Or, if we do know in advance what to put up top, where is “up top” anyway?

There is a fourth section within a Pattern that we haven’t discussed yet. A Pattern must contain GeneralInformation, Supplies, and Directions. A Pattern can also contain Directives. You’re not required to have Directives, but if you do have it, it comes first, before GeneralInformation.

Directives is a place to put instructions that you are going to refer to in your Directions. These instructions will be rendered in that “up top” part of your pattern. (If you were going to internationalize any messages in your pattern it is also where you would put the filenames that contain your bits of internationalized text; we will not discuss that right now though.)

FIRST EXAMPLE

Let’s consider the feather-and-fan stitch pattern that we’ve already looked at. The interesting row looked like this after we added a four-stitch border:

      row {
       k4,
       repeat to 4 before end {
       k2tog, k2tog, k2tog, // We could also say "k2tog 3" and KnitML will expand it.
       yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1,
       k2tog 3 // In the rendered pattern KnitML still spells out the three k2togs.
      },
      k4
    }

First let’s try lifting out the f+f part of this row into the Directives.

Directives {
  InstructionDefinitions {
    inlineInstruction 'f+f' [label:'do Feather and Fan'] {
       k2tog 3,
       yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1,
       k2tog 3
    }
  }
}

To refer to a name that we defined way up in the Directives, we say

ref 'f+f'

When we referred to a name we defined nearby in the Directions, we just used the name in single quotes: ‘feather-and-fan’. The “ref” tells KnitML to go look for this name in the Directives rather than nearby. This is how the four rows of feather and fan look now:

Directions {
  // ... cast on ...
  Instruction 'feather-and-fan' flat {
    row rightSide: k to end
    row: k 4, p to 4 before end, k 4
    row: k4, repeat to 4 before end { ref 'f+f' }, k4
    row: k to end
  }
  repeat 'feather-and-fan' until desiredLength
  // ... bind off ...
} 

It looks a little better already. When we render the pattern, that row of the Directions looks like “k4, do Feather and Fan to 4 sts before end, k4″. You can see how the label in the Directives got plugged into the Directions.

SECOND EXAMPLE

Can we move all four rows of feather and fan into the Directives? Yes! When we had just a piece of a row, we used an InlineInstruction to patch it into a row. When we have something spanning entire rows we use an Instruction. You have used an Instruction many times now down in the Directions. Up in the Directives there is a slight difference; we are required to say whether it is flat or round (down in the Directions this was optional.) Let’s give it a try:

// Pull out the four rows of feather and fan, just as they are,
// and see if that works.  (Foreshadowing: it doesn't.  If that bothers you,
// skip ahead to the version that works.)
Directives {
  InstructionDefinitions {
    Instruction 'feather+fan' [label:'Feather and Fan'] flat {
      row rightSide: k to end
      row: p to end
      row: k2tog 3, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, k2tog 3
      row: k to end
    }
  }
} 

Now let’s change the Directions to use this new definition of ‘feather+fan’:

Directions {
  co 36+4+4
  row: k to end
  row: k to end
  Instruction 'scarf-with-garter-border' flat {
    row: k 4, repeat to 4 before end { applyNextRow 'feather+fan' }, k4
  }
  repeat 'scarf-with-garter-border' until desiredLength
  row: k to end
  row: k to end
  row: bo all sts
} 

Let’s try rendering it. Oops! It doesn’t work and the KnitML Pattern Editor says that there are not enough stitches at row 3. That’s the first row where we are using the ‘feather+fan’ instructions. Why aren’t there enough stitches? Because the first row of ‘feather+fan’ says “k to end”, but then when we used it, we said “repeat this until there are 4 stitches left, then knit the last four stitches” – do you see that, having knit to the end, there won’t be 4 stitches left? What did we really mean to say? We really meant to say “k all the stitches that this stitch pattern is responsible for” and the pattern only has 18 stitches. Let’s fix that:

Directives {
  InstructionDefinitions {
    Instruction 'feather+fan' [label:'Feather and Fan'] flat {
      row rightSide: k 18 // This will work better than "k to end"
      row: p 18
      row: k2tog 3, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, k2tog 3
      row: k 18
    }
  }
}
// ...
// The Directions haven't changed at all; they were ok already.
Directions {
  co 36+4+4
  row: k to end
  row: k to end
  Instruction 'scarf-with-garter-border' flat {
    row: k 4, repeat 2 times { applyNextRow 'feather+fan' }, k4
  }
  repeat 'scarf-with-garter-border' until desiredLength
  row: k to end
  row: k to end
  row: bo all sts
} 

Now it works. The interesting part of the result looks like this:

Row 3: k4, work next row from Feather and Fan instruction 2 times, k4
Repeat row 3 until desired length.

EXERCISES:

1.
Just because I do it all the time, leave the ‘]’ out of the label in the first example and make sure you know what the error message looks like when you’re missing a brace, bracket, etc.:

// Here's the example without a ']'
Directives {
  InstructionDefinitions {
    inlineInstruction 'f+f' [label:'do Feather and Fan' {
       k2tog 3,
       yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1,
       k2tog 3
    }
  }
}

Ok, put the ']' back in there.

Create a new InlineInstruction for "yo, k1" (call it 'yo-k1' and give it any label you like, such as "[label:'(yo,k1)']"). Stop and make sure your pattern still renders (if it doesn't, take out what you wrote, copy the working InlineInstruction for 'f+f' and change it bit by bit into what you want for 'yo-k1'.)

Now, replace one of the six yo,k1 in 'f+f' with ref 'yo-k1'. Make sure your pattern still renders.

Finally, replace all of the six yo,k1 in 'f+f', by telling KnitML to repeat 'yo-k1' six times. This is what the definition of 'f+f' will look like in your rendered pattern when you are done: "Do Feather and Fan: k2tog, k2tog, k2tog, (yo,k1) 6 times, k2tog, k2tog, k2tog" (assuming your label is '(yo,k1)'.)

2.
Take the second example (the final working version of 'scarf-with-garter-border' using 'feather+fan') and define another stitch pattern by adding another Instruction to the Directives. Pick any simple stitch pattern such as seed (a.k.a. moss) or double seed (a.k.a. Irish moss) or ribbing. Use this pattern in your Directions instead of the k4 border; if the pattern is narrower than 4 sts, do two repeats of it on each side, otherwise doing it once on each side is fine. Make sure your cast-on number of stitches matches the number of stitches you're knitting.

ANSWERS:
1.

Directives {
  InstructionDefinitions {
      inlineInstruction 'yok1' [label:'(yo,k1)'] {
        yo, k1
      } // end inline yok1
      inlineInstruction 'f+f' [label:'do Feather and Fan'] {
       k2tog 3,
       repeat 6 times {ref 'yok1'},
       k2tog 3
      } // end inline f+f
    } // end ID
  } // end D
// Directions are unchanged

2.

Directives {
  InstructionDefinitions {
    Instruction 'feather+fan' [label:'Feather and Fan'] flat {
      row rightSide: k 18
      row: p 18
      row: k2tog 3, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, yo, k1, k2tog 3
      row: k 18
    } // end I
    Instruction 'moss' [label:'Irish Moss'] flat {
      row rightSide: k2, p2
      row: k2, p2
      row: p2, k2
      row: p2, k2
    } // end I
  } // end ID
} // end D
// ...
Directions {
  co 36+4+4
  row: k to end
  row: k to end
  Instruction 'scarf-with-garter-border' flat {
    row {
      applyNextRow 'moss',
      repeat 2 times { applyNextRow 'feather+fan' }, applyNextRow 'moss'
    } // end row
  } // end Instruction
  repeat 'scarf-with-garter-border' until desiredLength
  row: k to end
  row: k to end
  row: bo all sts
} // end Directions

TERMS

Each chapter will contain a (rather hasty at present) list of the terms in Appendix B. Knitting Expression Language Reference that have been introduced in that chapter.

applyNextRow
directives
inlineInstruction
instructionDefinitions
ref