Working with Files

TL;DR

Yoink lets you stitch files together by declaring .yoink commands in your source text. The parser reads the root file, resolves each include, and returns a single, expanded document.

• Add .yoink <path> lines where you want content to be inserted.
• Open the root file and pass it to yoink.Parse with the file name.
• Use the returned string as the fully resolved document.

Installing the Library

Use go get to install the latest version of the library.

go get -u github.com/tedla-brandsema/yoink@latest

Then, import Yoink in your application:

import "github.com/tedla-brandsema/yoink"

Local Files

You can include local files by adding the .yoink command at the start of a line, followed by the name of the file to include. Below is an example file that contains two such commands.

            
Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

.yoink sonnet-18-quatrains.txt

.yoink sonnet-18-rhyming-couplet.txt
            
        

Above we see two .yoink commands: one command pointing to sonnet-18-quatrains.txt and the other to sonnet-18-rhyming-couplet.txt.

To let Yoink resolve those commands, we first need to open our root file and then pass it to yoink.Parse in the form of an io.Reader.

            
package main

import (
	"context"
	"fmt"
	"github.com/tedla-brandsema/yoink"
	"os"
)

func main() {
	// Open the root file
	name := "./data/sonnet-18.txt"
	file, err := os.Open(name)
	if err != nil {
		panic(err)
	}
	defer file.Close()

	// Resolve .yoink commands in the root file
	txt, err := yoink.Parse(context.Background(), file, name)
	if err != nil {
		panic(err)
	}
	fmt.Println(txt)
}
            
         

Running the program yields the following result:

            
Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;

Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;

But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:

So long as men can breathe or eyes can see,
So long lives this, and this gives life to thee.                    
            
        

Remote Files

Including remote files works much the same as working with local files; you add the .yoink command to the start of a line, but instead of adding the name of the file to include, you add the URL of the file to include.

In the example below, there are two .yoink commands pointing to URLs with raw text data.

        
Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

.yoink https://raw.githubusercontent.com/tedla-brandsema/examples/refs/heads/main/yoink/1_local/data/sonnet-18-quatrains.txt

.yoink https://raw.githubusercontent.com/tedla-brandsema/examples/refs/heads/main/yoink/1_local/data/sonnet-18-rhyming-couplet.txt
        
    

Parsing of a file that contains a .yoink command that points to a URL is exactly the same as parsing a file with .yoink commands that point to local files.

        
package main

import (
	"context"
	"fmt"
	"github.com/tedla-brandsema/yoink"
	"os"
)

func main() {
	// Open the root file
	name := "./data/sonnet-18-remote.txt"
	file, err := os.Open(name)
	if err != nil {
		panic(err)
	}
	defer file.Close()

	// Resolve .yoink commands in the root file
	txt, err := yoink.Parse(context.Background(), file, name)
	if err != nil {
		panic(err)
	}
	fmt.Println(txt)
}            
        
    

Running the program yields the exact same result as the previous example, only now over HTTPS instead of locally.

        
Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;

Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;

But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:

So long as men can breathe or eyes can see,
So long lives this, and this gives life to thee.