stashcache | importing stash

I'm not a big fan of typing on a phone keyboard.

It works fine for quick, short entries, but let’s face it: you’re not looking at my app because you have just a few colors of thread to keep track of. (It’s okay, I didn’t write it for that reason either.)

It was really important to me that data entry was something you could do easily, on your computer with a keyboard that’s easy to type on. That’s why I wrote the importer (and exporter!) – to make it easy to build up the information about your stash. All you need is a program that will produce a text file – Notepad (for Windows) or TextEdit (for Mac) is great!

The importer works by following a very specific set of rules to interpret the data that you enter and produce the stash list. As a result, it is very sensitive to making sure you follow the proper format. There’s a whole explanation for what is expected below, as well some template files and stash builders for commonly used items (like DMC or Anchor floss).

I encourage you to start small – it’s much easier to find a mistake in the file format when the file is very short. Every import adds to your existing stash, so there’s no reason to have to fit everything in at once. Also, be sure to export your stash as well – both to see what the program expects and to have a backup!

File Formatting

The text file for import (and export) has several sections. It starts with items in stash (which you will enter when typing up your stash) and then moves to items not in the stash. Between each type of item is a marker (three asterisks – ***), for a total of six. If you’re entering multiple items of the same type, there is also an internal marker (three dashes – —). The type marker must be there even if you have not entered the item type before it – this is how the app keeps track of what type of item it is importing.

The expected order of items in the file is:

– threads in the stash
– unassigned fabric
– embellishments in the stash
– patterns in the stash
– thread not in a stash or pattern
– embellishments not in a stash or pattern
– patterns no longer in the stash

Fabric assigned to a pattern and fabric for completed projects are associated with the pattern itself. When importing data for your stash, you can always create the link between fabric and pattern later.

The formatting for each item type is the same whether it is in or out of the stash, or incorporated into another item (like threads called for by a pattern). The only exception to this are fabrics, which may store some additional information when associated with a pattern.

Below, I’ve included information about the expected format for each item type, as well as image examples from my own stash. The information that goes on each line is indicated like [this]. If there is no indication inside those brackets that the line is optional, it must be included, even if just as an empty line. Otherwise the importer will not work correctly.

Thread Format

There are four main pieces of information needed for thread: who the manufacturer is, what type of thread it is, the color code, and how many skeins are in your stash or called for by a pattern, represented by the number of times the color code is repeated. (It is possible to leave some of the manufacturer and type fields blank, although I do not recommend it – that will make it harder to sort through your stash.)

The expected format for threads is:

[manufacturer]
[type]
[code1]
[code2]
[code2]
[code3]

In this example, the three threads share a manufacturer and type. The thread named “code2” has a quantity of 2 – either in the stash, or a pattern calls for two skeins of it. To include thread from a different manufacturer, the item marker (—) should be on the line between the last code and the next manufacturer.

Note: when dealing with thread in patterns, the item marker is replaced by a single dash (-). See the Pattern Format for more information.

Fabric Format

The important information for fabric is manufacturer, type, color, count, and size. Count is expected as a whole number – no decimals please – while width and height can have decimals. The importer will let you know if these lines do not have a number as expected, or if there is a formatting issue with that number – although it is unable to tell you exactly where the issue is.

The expected format is:

[manufacturer]
[type]
[color]
[count]
[width]
[height]
[optional – notes]

An item marker (—) should be included between each fabric entered.

If you include any * or – characters in the notes section of the fabric, they will show with extra spaces in the export file in order to avoid problems with the importer.

Wait, my exported file looks slightly different. What's going on?

There is additional information included with the fabric entry when dealing with a file exported by the program in some circumstances. This is determined by if a project is “in progress” or completed. In those situations, the fabric format looks like this:

[manufacturer]
[type]
[color]
[count]
[width]
[height]
[in use – if in progress]
[start date – if in progress or completed]
[end date – if completed]
[optional – notes]

Embellishment Format

There are four main pieces of information needed for embellishments: who the manufacturer is, what type of embellishment it is, the code or name, and how many are in your stash or called for by a pattern, represented by the number of times the code/name is repeated.

Similar to threads, the expected format for embellishments is:

[manufacturer]
[type]
[code1]
[code2]
[code2]
[code3]

In this example, the three embellishments share a manufacturer and type. The embellishment named “code2” has a quantity of 2 – either in the stash, or a pattern calls for two of them. To include embellishments from a different manufacturer, the item marker (—) should be on the line between the last code and the next manufacturer.

Note: when dealing with embellishments in patterns, the item marker is replaced by a single dash (-). See the Pattern Format for more information.

Pattern Format

Patterns require the most information and thus have the most complex formatting requirements. The important information for the pattern itself is the designer, name, and size in stitches (width and height). The stitches should be whole numbers, no decimals. The importer will let you know if these lines do not have a number as expected, or if there is a formatting issue with that number – although it is unable to tell you exactly where the issue is.

There are also fabric, threads, and embellishments associated with the pattern. To distinguish between these, a sub-type marker (*) is used. There is also a sub-item marker (-) to distinguish between items. These things are optional, however – the only requirement is to have the three sub-type markers (*) present, so that the importer knows that you aren’t entering this information. (See the short pattern template below.)

The expected format is:

[name]
[designer]
[width]
[height]
*
[fabric information – optional]
*
[thread information – optional]
*
[embellishment information – optional]

An item marker (—) should be included between each pattern entered. Fabric, thread, and embellishment information follows the format laid out for those item types, with the difference of using the sub-item marker (-) instead of the item marker (—) when separating different manufacturers.

The exported file doesn't look quite like that. What's going on?

There is additional information included with the pattern entry when dealing with a file exported by the program in some circumstances. This is determined by if a project is “kitted” or has finishes associated with it. In those situations, the format looks like this:

[name]
[designer]
[width]
[height]
[kitted – only if kitted]
*
[fabric information]
*
[thread information]
*
[embellishment information]
* (if finishes exist)
[fabric information for finishes]

Whether the pattern is included in the stash or not is determined by its placement in the overall structure of the file.

Templates and StashBuilders

I realize that the format information can be very intimidating, so I have provided template files that you can modify in order to build your stash. I recommend starting small – the app can tell you if a number wasn’t formatted incorrectly, or if a line is missing somewhere unexpectedly, but it can’t tell you where in the file that happens. It’s much easier to find the mistake in a small file. Back up regularly as well! It makes things much easier to fix if something goes wrong.

I have also included some stash builder files for common thread types. Just import these files to add the information to your app and then you can edit the quantities in your stash using the in-app dialog box.

Template Files

Modify these to add a particular element to your stash. Right-click and select “Save Link As” to download them to your computer.

– thread template
– fabric template
– embellishment template
– pattern template
– short pattern template – just the name, designer, and stitch count

Stash Builders

These will import the data for the thread into your app, but will not add them to your stash – you will need to edit the quantities in app to do that. The lists are as complete as I can make them, thanks to the generous assistance of Amanda, Arlene, Brittany, and Paula.

– Anchor
– Caron Waterlilies
– Classic Colorworks (formerly Crescent Colors)
– Dinky Dyes
– DMC
– DMC Variations
– Gentle Art Sampler Threads (thread numbers not included)
– Gloriana
– Kreinik #4 Braid
– Kreinik #8 Braid
– Kreinik Blending Filament
– Mill Hill Beads
– Mill Hill Treasures
– Needlepaints
– Needlepoint Silks
– Rainbow Gallery Treasure Braid
– Silk ‘N Colors
– Weeks Dye Works (thread numbers not included)

If you are interested in seeing something else here, please contact me and I will see what I can do. Also let me know if there are errors so I can correct them – I am happy to give credit where it is due!