cooklang

func (*Comment) GetNext ¶ added in v0.3.0

func (cm *Comment) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Comment) Render ¶ added in v0.3.0

func (cm Comment) Render() string

Render returns the Cooklang syntax representation of this comment. Examples: "-- comment text" for line comments, "[- comment text -]" for block comments

func (Comment) RenderDisplay ¶ added in v0.3.0

func (cm Comment) RenderDisplay() string

RenderDisplay returns comment text suitable for display.

func (*Comment) SetNext ¶ added in v0.3.0

func (cm *Comment) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*Cookware) GetNext ¶

func (c *Cookware) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Cookware) Render ¶

func (c Cookware) Render() string

Render returns the Cooklang syntax representation of this cookware. Examples: "#pot{}", "#bowl{2}", "#oven{}(preheated)"

func (Cookware) RenderDisplay ¶

func (c Cookware) RenderDisplay() string

RenderDisplay returns cookware in plain text format suitable for display. Returns just the cookware name.

func (*Cookware) SetNext ¶

func (c *Cookware) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*FileSystemResolver) Resolve ¶ added in v1.0.5

func (r *FileSystemResolver) Resolve(path string) (*Recipe, error)

Resolve reads and parses a .cook file relative to the base path. It caches results and detects cycles.

func (*FrontmatterEditor) AppendToArray ¶

func (fe *FrontmatterEditor) AppendToArray(key, value string) error

AppendToArray appends a value to an array field (tags or images). Unlike FrontmatterEditor.SetMetadata, this adds a single item without replacing existing values. The underlying storage is []string, not a comma-separated string.

Parameters:

• key: The array field name ("tags" or "images")
• value: The single value to append

Returns:

• error: An error if the field is not an array field

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
// Assuming tags are currently ["italian"]
editor.AppendToArray("tags", "vegetarian") // tags: ["italian", "vegetarian"]
editor.AppendToArray("tags", "healthy")    // tags: ["italian", "vegetarian", "healthy"]
editor.Save()

func (*FrontmatterEditor) DeleteMetadata ¶

func (fe *FrontmatterEditor) DeleteMetadata(key string) error

DeleteMetadata removes a metadata key from the recipe. For structured fields, this clears the value. For custom fields, it removes the entry.

Parameters:

• key: The metadata key to delete

Returns:

• error: Currently always returns nil (reserved for future validation)

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
editor.DeleteMetadata("author")
editor.DeleteMetadata("custom_field")
editor.Save()

func (*FrontmatterEditor) GetAllMetadata ¶

func (fe *FrontmatterEditor) GetAllMetadata() map[string]string

GetAllMetadata returns all metadata as a map. This includes both structured fields (title, cuisine, etc.) and custom metadata.

Returns:

• map[string]string: All metadata key-value pairs

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
allMeta := editor.GetAllMetadata()
for key, value := range allMeta {
    fmt.Printf("%s: %s\n", key, value)
}

func (*FrontmatterEditor) GetContent ¶

func (fe *FrontmatterEditor) GetContent() string

GetContent returns the original file content as read from disk.

Returns:

• string: The original file content

func (*FrontmatterEditor) GetMetadata ¶

func (fe *FrontmatterEditor) GetMetadata(key string) (string, bool)

GetMetadata retrieves a metadata value by key. It checks structured fields first (title, cuisine, etc.) then falls back to the generic metadata map.

For array fields (tags, images), the value is returned as a comma-separated string. Use FrontmatterEditor.AppendToArray and FrontmatterEditor.RemoveFromArray for individual item operations.

Parameters:

• key: The metadata key to retrieve

Returns:

• string: The metadata value (comma-separated for array fields)
• bool: true if the key exists, false otherwise

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
if title, ok := editor.GetMetadata("title"); ok {
    fmt.Printf("Recipe title: %s\n", title)
}
if tags, ok := editor.GetMetadata("tags"); ok {
    fmt.Printf("Tags: %s\n", tags) // e.g., "italian, pasta, quick"
}

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	// Demonstrates the pattern for getting metadata
	recipeText := `---
title: Chocolate Cake
difficulty: Medium
prep_time: 30 minutes
---
Mix ingredients.`

	recipe, _ := cooklang.ParseString(recipeText)

	// Access metadata directly from recipe
	fmt.Printf("Title: %s\n", recipe.Title)
	fmt.Printf("Difficulty: %s\n", recipe.Difficulty)
	fmt.Printf("Prep time: %s\n", recipe.PrepTime)
}

Output:
Title: Chocolate Cake
Difficulty: Medium
Prep time: 30 minutes

func (*FrontmatterEditor) GetUpdatedContent ¶

func (fe *FrontmatterEditor) GetUpdatedContent() string

GetUpdatedContent returns the updated content without saving to disk. This is useful for previewing changes before committing them.

Returns:

• string: The complete file content with updated frontmatter

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
editor.SetMetadata("title", "Preview")
preview := editor.GetUpdatedContent()
fmt.Println(preview) // See changes without saving

func (*FrontmatterEditor) RemoveFromArray ¶

func (fe *FrontmatterEditor) RemoveFromArray(key, value string) error

RemoveFromArray removes a value from an array field (tags or images). All occurrences of the value are removed. The underlying storage is []string.

Parameters:

• key: The array field name ("tags" or "images")
• value: The single value to remove

Returns:

• error: An error if the field is not an array field

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
// Assuming tags are currently ["italian", "unhealthy", "quick"]
editor.RemoveFromArray("tags", "unhealthy") // tags: ["italian", "quick"]
editor.Save()

func (*FrontmatterEditor) Save ¶

func (fe *FrontmatterEditor) Save() error

Save writes the updated recipe back to the original file. The recipe body (instructions) is preserved; only the frontmatter is updated.

Returns:

• error: Any error encountered during file writing

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
editor.SetMetadata("title", "Updated Title")
if err := editor.Save(); err != nil {
    log.Fatal(err)
}

func (*FrontmatterEditor) SaveAs ¶

func (fe *FrontmatterEditor) SaveAs(filePath string) error

SaveAs writes the updated recipe to a specified file path. The recipe body (instructions) is preserved; only the frontmatter is updated.

Parameters:

• filePath: The destination file path

Returns:

• error: Any error encountered during file writing

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
editor.SetMetadata("title", "Updated Recipe")
editor.SaveAs("recipe_v2.cook")

func (*FrontmatterEditor) SetMetadata ¶

func (fe *FrontmatterEditor) SetMetadata(key, value string) error

SetMetadata sets or updates a metadata value. For array fields (tags, images), the value should be comma-separated; it will be split and stored as a []string internally. To add/remove individual items without replacing the entire array, use FrontmatterEditor.AppendToArray and FrontmatterEditor.RemoveFromArray instead.

For structured fields (servings, date), the value is validated and parsed.

Parameters:

• key: The metadata key to set
• value: The value to set (comma-separated for array fields)

Returns:

• error: Validation error for structured fields (e.g., invalid date format)

Example:

editor, _ := cooklang.NewFrontmatterEditor("recipe.cook")
editor.SetMetadata("title", "Amazing Lasagna")
editor.SetMetadata("servings", "6")
editor.SetMetadata("tags", "italian, pasta, main course") // replaces all tags
editor.SetMetadata("date", "2024-01-15")
editor.Save()

func (*Ingredient) CanConvertTo ¶

func (i *Ingredient) CanConvertTo(targetUnitStr string) bool

CanConvertTo checks if the ingredient can be converted to the target unit. This allows validating conversions before attempting them.

Parameters:

• targetUnitStr: The unit to check conversion compatibility with

Returns:

• bool: true if conversion is possible, false otherwise

Example:

ingredient := &Ingredient{Name: "water", Quantity: 250, Unit: "ml"}
if ingredient.CanConvertTo("cup") {
    converted, _ := ingredient.ConvertTo("cup")
    fmt.Printf("Can convert: %.2f %s\n", converted.Quantity, converted.Unit)
}

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @flour{200%g}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	flour := recipe.GetIngredients().Ingredients[0]

	// Check various conversions
	fmt.Printf("Can convert to kg: %v\n", flour.CanConvertTo("kg"))
	fmt.Printf("Can convert to oz: %v\n", flour.CanConvertTo("oz"))
	fmt.Printf("Can convert to ml: %v\n", flour.CanConvertTo("ml"))
}

Output:
Can convert to kg: true
Can convert to oz: true
Can convert to ml: false

func (*Ingredient) ConvertTo ¶

func (i *Ingredient) ConvertTo(targetUnitStr string) (*Ingredient, error)

ConvertTo converts the ingredient to a different unit if possible. The conversion uses either custom cooking unit conversions (for common units like cups, tbsp, oz) or the go-units library for scientific units.

Parameters:

• targetUnitStr: The target unit to convert to (e.g., "g", "cup", "ml")

Returns:

• *Ingredient: A new ingredient with the converted quantity and unit
• error: Error if conversion is not possible (incompatible units, "some" quantity, etc.)

Example:

ingredient := &Ingredient{Name: "flour", Quantity: 2, Unit: "cup"}
converted, err := ingredient.ConvertTo("g")
if err == nil {
    fmt.Printf("%.0f %s\n", converted.Quantity, converted.Unit) // "473 g"
}

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @water{500%ml}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	ingredients := recipe.GetIngredients()
	water := ingredients.Ingredients[0]

	// Convert from milliliters to cups
	converted, err := water.ConvertTo("cup")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Original: %.0f %s\n", water.Quantity, water.Unit)
	fmt.Printf("Converted: %.2f %s\n", converted.Quantity, converted.Unit)
}

Output:
Original: 500 ml
Converted: 2.11 cup

func (*Ingredient) ConvertToSystem ¶

func (i *Ingredient) ConvertToSystem(system UnitSystem) *Ingredient

ConvertToSystem converts an ingredient to the target unit system. The conversion selects an appropriate unit based on the ingredient's unit type (mass or volume) and converts the quantity accordingly.

If the ingredient has no TypedUnit or has "some" quantity (-1), a copy is returned unchanged.

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS, UnitSystemImperial)

Returns:

• *Ingredient: A new ingredient with converted quantity and unit

Example:

flour := cooklang.NewIngredient("flour", 500, "g")
usFlour := flour.ConvertToSystem(cooklang.UnitSystemUS)
fmt.Printf("%v %s\n", usFlour.Quantity, usFlour.Unit) // "17.6 oz"

func (*Ingredient) ConvertToSystemBartender ¶

func (i *Ingredient) ConvertToSystemBartender(system UnitSystem) *Ingredient

ConvertToSystemBartender converts an ingredient using bartender-friendly conversions. It uses practical measurements like dashes for very small amounts (<3ml), and skips conversion for cocktail-specific units (dash, splash, etc.).

Features:

• Practical oz/ml conversion (30ml = 1oz)
• Smart unit selection based on quantity
• Dashes for tiny amounts (≤3ml)
• Preserves cocktail-specific units

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS)

Returns:

• *Ingredient: A new ingredient with bartender-friendly quantity and unit

Example:

vodka := cooklang.NewIngredient("vodka", 45, "ml")
usVodka := vodka.ConvertToSystemBartender(cooklang.UnitSystemUS)
fmt.Printf("%v %s\n", usVodka.Quantity, usVodka.Unit) // "1.5 oz"

func (*Ingredient) FormatQuantityBartender ¶

func (i *Ingredient) FormatQuantityBartender() string

FormatQuantityBartender formats an ingredient's quantity using bartender-friendly formatting. This uses fractions instead of decimals (e.g., "1/2" instead of "0.5") and handles pluralization appropriately.

Returns:

• string: Formatted quantity string (e.g., "1 1/2 oz", "some", "")

Example:

vodka := cooklang.NewIngredient("vodka", 1.5, "oz")
fmt.Println(vodka.FormatQuantityBartender()) // "1 1/2 oz"

func (*Ingredient) GetNext ¶

func (i *Ingredient) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*Ingredient) GetUnitType ¶

func (i *Ingredient) GetUnitType() string

GetUnitType returns the ingredient's unit quantity type (e.g., "mass", "volume", "length"). This helps categorize ingredients and determine valid conversions.

Returns:

• string: The quantity type ("mass", "volume", "length", "temperature", "time", "energy", or "")

Example:

ingredient := &Ingredient{Name: "flour", Quantity: 500, Unit: "g"}
fmt.Println(ingredient.GetUnitType()) // "mass"

ingredient2 := &Ingredient{Name: "milk", Quantity: 2, Unit: "cup"}
fmt.Println(ingredient2.GetUnitType()) // "volume"

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @water{500%ml}, @flour{200%g}, and @vanilla{1%tsp}.`

	recipe, _ := cooklang.ParseString(recipeText)
	ingredients := recipe.GetIngredients()

	for _, ing := range ingredients.Ingredients {
		unitType := ing.GetUnitType()
		fmt.Printf("%s: %s\n", ing.Name, unitType)
	}
}

Output:
water: volume
flour: mass
vanilla: volume

func (Ingredient) Render ¶

func (i Ingredient) Render() string

Render returns the Cooklang syntax representation of this ingredient. Examples: "@flour{500%g}", "@salt{}", "@milk{2%cups}(cold)", "@yeast{=1%packet}", "@?thyme{2%sprigs}"

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @garlic{3%cloves}(minced) and @salt{}.`

	recipe, _ := cooklang.ParseString(recipeText)
	ingredients := recipe.GetIngredients()

	for _, ing := range ingredients.Ingredients {
		fmt.Println(ing.Render())
	}
}

Output:
@garlic{3%cloves}(minced)
@salt{}

func (Ingredient) RenderDisplay ¶

func (i Ingredient) RenderDisplay() string

RenderDisplay returns ingredient in plain text format suitable for display. Examples: "2 cups flour", "500 g flour", "salt", "2 sprigs thyme (optional)" Uses bartender-friendly fraction formatting (e.g., "1/2 oz" instead of "0.5 oz") When quantity is unspecified (e.g., @salt{}), returns just the ingredient name. Optional ingredients have "(optional)" appended.

func (*Ingredient) SetNext ¶

func (i *Ingredient) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*IngredientList) Add ¶

func (il *IngredientList) Add(ingredient *Ingredient)

Add adds an ingredient to the list.

Parameters:

• ingredient: The ingredient to add

Example:

list := cooklang.NewIngredientList()
list.Add(&cooklang.Ingredient{Name: "sugar", Quantity: 100, Unit: "g"})
list.Add(&cooklang.Ingredient{Name: "flour", Quantity: 2, Unit: "cup"})

func (*IngredientList) ConsolidateByName ¶

func (il *IngredientList) ConsolidateByName(targetUnit string) (*IngredientList, error)

ConsolidateByName consolidates ingredients with the same name, converting to a common unit when possible. This is useful for creating shopping lists where multiple mentions of the same ingredient should be combined into a single entry.

If targetUnit is empty, the method attempts to find a common unit from the ingredients. If targetUnit is specified, all compatible ingredients are converted to that unit before consolidation.

Ingredients with "some" quantity (-1) or incompatible units are kept separate.

Parameters:

• targetUnit: The unit to convert all ingredients to (empty string to auto-detect)

Returns:

• *IngredientList: A new list with consolidated ingredients
• error: Any error encountered during consolidation

Example:

list := cooklang.NewIngredientList()
list.Add(&cooklang.Ingredient{Name: "flour", Quantity: 100, Unit: "g"})
list.Add(&cooklang.Ingredient{Name: "flour", Quantity: 150, Unit: "g"})
consolidated, _ := list.ConsolidateByName("")
// consolidated will have one "flour" entry with 250g

package main

import (
	"fmt"
	"log"
	"sort"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @flour{200%g} to bowl.
Mix with @flour{300%g} and @sugar{100%g}.
Add @sugar{50%g} for sweetness.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	ingredients := recipe.GetIngredients()
	consolidated, err := ingredients.ConsolidateByName("")
	if err != nil {
		log.Fatal(err)
	}

	// Sort ingredients by name for consistent output
	sort.Slice(consolidated.Ingredients, func(i, j int) bool {
		return consolidated.Ingredients[i].Name < consolidated.Ingredients[j].Name
	})

	fmt.Println("Consolidated ingredients:")
	for _, ing := range consolidated.Ingredients {
		fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
	}
}

Output:
Consolidated ingredients:
- flour: 500 g
- sugar: 150 g

func (*IngredientList) ConvertToSystem ¶

func (il *IngredientList) ConvertToSystem(system UnitSystem) *IngredientList

ConvertToSystem converts all ingredients in the list to the target unit system. Each ingredient is converted individually using Ingredient.ConvertToSystem. Ingredients that cannot be converted (no TypedUnit or "some" quantity) are copied as-is.

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS, UnitSystemImperial)

Returns:

• *IngredientList: A new list with converted ingredients

Example:

metricList := recipe.GetIngredients()
usList := metricList.ConvertToSystem(cooklang.UnitSystemUS)

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @water{2%cup}, @flour{500%g}, and @sugar{1%lb}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	ingredients := recipe.GetIngredients()

	// Convert to metric system
	metric := ingredients.ConvertToSystem(cooklang.UnitSystemMetric)

	fmt.Println("Metric ingredients:")
	for _, ing := range metric.Ingredients {
		fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
	}
}

Output:
Metric ingredients:
- water: 473 ml
- flour: 500 g
- sugar: 454 g

func (*IngredientList) ConvertToSystemBartender ¶

func (il *IngredientList) ConvertToSystemBartender(system UnitSystem) *IngredientList

ConvertToSystemBartender converts all ingredients using bartender-friendly conversions. This uses practical bartender measurements (30ml = 1oz instead of 29.5735ml) and smart unit selection (dashes for tiny amounts, friendly fractions).

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS)

Returns:

• *IngredientList: A new list with bartender-friendly converted ingredients

Example:

ingredients := cocktail.GetIngredients()
usBar := ingredients.ConvertToSystemBartender(cooklang.UnitSystemUS)

func (*IngredientList) ConvertToSystemWithConsolidation ¶

func (il *IngredientList) ConvertToSystemWithConsolidation(system UnitSystem) (*IngredientList, error)

ConvertToSystemWithConsolidation converts ingredients to a target system and consolidates by name. This combines ConvertToSystem and ConsolidateByName in a single operation.

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS, UnitSystemImperial)

Returns:

• *IngredientList: A new list with converted and consolidated ingredients
• error: Any error encountered during consolidation

Example:

ingredients := recipe.GetIngredients()
usList, _ := ingredients.ConvertToSystemWithConsolidation(cooklang.UnitSystemUS)

func (*IngredientList) GetIngredientsByName ¶

func (il *IngredientList) GetIngredientsByName(name string) []*Ingredient

GetIngredientsByName returns all ingredients with the given name. This is useful for finding duplicate ingredients before consolidation or for extracting specific ingredients from a list.

Parameters:

• name: The ingredient name to search for (case-sensitive)

Returns:

• []*Ingredient: Slice of matching ingredients (empty if none found)

Example:

list := recipe.GetIngredients()
flourEntries := list.GetIngredientsByName("flour")
for _, f := range flourEntries {
    fmt.Printf("Found %v %s flour\n", f.Quantity, f.Unit)
}

func (*IngredientList) ToMap ¶

func (il *IngredientList) ToMap() map[string]string

ToMap returns a map of ingredient names to their formatted quantities. This is useful for displaying shopping lists in a simple key-value format.

The quantity formatting follows these rules:

• Whole numbers are shown without decimals (e.g., "100 g")
• Fractional quantities show one decimal place (e.g., "1.5 cup")
• "Some" quantities (-1) are displayed as "some" or "some [unit]"
• Unitless ingredients show just the quantity or "some"

Returns:

• map[string]string: Map of ingredient names to formatted quantity strings

Example:

list := recipe.GetIngredients()
for name, qty := range list.ToMap() {
    fmt.Printf("- %s: %s\n", name, qty)
}
// Output:
// - flour: 500 g
// - eggs: 3
// - salt: some

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Use @flour{500%g}, @sugar{200%g}, and @eggs{3}.`

	recipe, _ := cooklang.ParseString(recipeText)
	ingredients := recipe.GetIngredients()

	ingredientMap := ingredients.ToMap()

	// Print in deterministic order for test
	fmt.Printf("eggs: %s\n", ingredientMap["eggs"])
	fmt.Printf("flour: %s\n", ingredientMap["flour"])
	fmt.Printf("sugar: %s\n", ingredientMap["sugar"])
}

Output:
eggs: 3
flour: 500 g
sugar: 200 g

func (*Instruction) GetNext ¶

func (inst *Instruction) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Instruction) Render ¶

func (inst Instruction) Render() string

Render returns the plain text instruction.

func (Instruction) RenderDisplay ¶

func (inst Instruction) RenderDisplay() string

RenderDisplay returns instruction text suitable for display (same as Render for Instruction).

func (*Instruction) SetNext ¶

func (inst *Instruction) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*Note) GetNext ¶ added in v0.4.0

func (n *Note) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Note) Render ¶ added in v0.4.0

func (n Note) Render() string

Render returns the Cooklang syntax representation of this note. Example: "> This is a note"

func (Note) RenderDisplay ¶ added in v0.4.0

func (n Note) RenderDisplay() string

RenderDisplay returns note text suitable for display.

func (*Note) SetNext ¶ added in v0.4.0

func (n *Note) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*Recipe) GetCollectedIngredients ¶

func (r *Recipe) GetCollectedIngredients() (*IngredientList, error)

GetCollectedIngredients returns a consolidated list of all ingredients from the recipe. This combines GetIngredients() and ConsolidateByName() into a single convenient function. Duplicate ingredients with compatible units are combined into single entries.

Returns:

• *IngredientList: A consolidated list of ingredients
• error: Any error encountered during consolidation

Example:

recipe, _ := cooklang.ParseFile("cake.cook")
ingredients, _ := recipe.GetCollectedIngredients()
for _, ing := range ingredients.Ingredients {
    fmt.Printf("%s: %v %s\n", ing.Name, ing.Quantity, ing.Unit)
}

package main

import (
	"fmt"
	"log"
	"sort"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `First layer: @cheese{100%g} and @tomato{2}.
Second layer: @cheese{150%g} and @tomato{3}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	collected, err := recipe.GetCollectedIngredients()
	if err != nil {
		log.Fatal(err)
	}

	// Sort ingredients by name for consistent output
	sort.Slice(collected.Ingredients, func(i, j int) bool {
		return collected.Ingredients[i].Name < collected.Ingredients[j].Name
	})

	fmt.Println("Shopping list:")
	for _, ing := range collected.Ingredients {
		if ing.Unit != "" {
			fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
		} else {
			fmt.Printf("- %s: %.0f\n", ing.Name, ing.Quantity)
		}
	}
}

Output:
Shopping list:
- cheese: 250 g
- tomato: 5

func (*Recipe) GetCollectedIngredientsMap ¶

func (r *Recipe) GetCollectedIngredientsMap() (map[string]string, error)

GetCollectedIngredientsMap returns a map of ingredient names to their consolidated quantities. This is useful for creating simple shopping lists or ingredient summaries.

Returns:

• map[string]string: A map of ingredient names to formatted quantity strings
• error: Any error encountered during consolidation

Example:

recipe, _ := cooklang.ParseFile("pasta.cook")
ingredientMap, _ := recipe.GetCollectedIngredientsMap()
for name, qty := range ingredientMap {
    fmt.Printf("- %s: %s\n", name, qty)
}

package main

import (
	"fmt"
	"log"
	"sort"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @water{1%l}, @salt{1%tsp}, and @salt{0.5%tsp}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	shoppingMap, err := recipe.GetCollectedIngredientsMap()
	if err != nil {
		log.Fatal(err)
	}

	// Sort keys for consistent output
	keys := make([]string, 0, len(shoppingMap))
	for name := range shoppingMap {
		keys = append(keys, name)
	}
	sort.Strings(keys)

	for _, name := range keys {
		fmt.Printf("%s: %s\n", name, shoppingMap[name])
	}
}

Output:
salt: 1.5 tsp
water: 1 l

func (*Recipe) GetCollectedIngredientsWithUnit ¶

func (r *Recipe) GetCollectedIngredientsWithUnit(targetUnit string) (*IngredientList, error)

GetCollectedIngredientsWithUnit returns a consolidated list of all ingredients from the recipe, converting them to the specified target unit when possible.

Parameters:

• targetUnit: The unit to convert compatible ingredients to (e.g., "g", "ml", "oz")

Returns:

• *IngredientList: A consolidated list with converted ingredients
• error: Any error encountered during consolidation

Example:

recipe, _ := cooklang.ParseFile("cake.cook")
// Get all ingredients in grams
ingredients, _ := recipe.GetCollectedIngredientsWithUnit("g")

func (*Recipe) GetCookware ¶

func (r *Recipe) GetCookware() []*Cookware

GetCookware returns all cookware items from a recipe, extracted from all steps.

Returns:

• []*Cookware: A slice containing all cookware items in order of appearance

Example:

recipe, _ := cooklang.ParseFile("pasta.cook")
cookware := recipe.GetCookware()
for _, cw := range cookware {
    fmt.Printf("%s (qty: %d)\n", cw.Name, cw.Quantity)
}

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Mix ingredients in a #mixing bowl{}.
Transfer to a #baking dish{} and bake in an #oven{}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	cookware := recipe.GetCookware()
	fmt.Printf("Cookware needed (%d items):\n", len(cookware))
	for _, cw := range cookware {
		fmt.Printf("- %s\n", cw.Name)
	}
}

Output:
Cookware needed (3 items):
- mixing bowl
- baking dish
- oven

func (*Recipe) GetImperialShoppingList ¶

func (r *Recipe) GetImperialShoppingList() (map[string]string, error)

GetImperialShoppingList returns a shopping list with all ingredients converted to Imperial units. Common conversions include: pints, fluid ounces, pounds, ounces.

Returns:

• map[string]string: A map of ingredient names to quantities
• error: Any error encountered during conversion

func (*Recipe) GetIngredients ¶

func (r *Recipe) GetIngredients() *IngredientList

GetIngredients returns all ingredients from a recipe, extracted from all steps. This traverses the recipe's linked list structure to collect every ingredient mention.

Returns:

• *IngredientList: A list containing all ingredients in order of appearance

Example:

recipe, _ := cooklang.ParseFile("lasagna.cook")
ingredients := recipe.GetIngredients()
for _, ing := range ingredients.Ingredients {
    fmt.Printf("%s: %.1f %s\n", ing.Name, ing.Quantity, ing.Unit)
}

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Mix @flour{200%g}, @sugar{150%g}, and @butter{100%g}.
Add @eggs{2} and @vanilla{1%tsp}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	ingredients := recipe.GetIngredients()
	fmt.Printf("Found %d ingredients:\n", len(ingredients.Ingredients))
	for _, ing := range ingredients.Ingredients {
		if ing.Unit != "" {
			fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
		} else {
			fmt.Printf("- %s: %.0f\n", ing.Name, ing.Quantity)
		}
	}
}

Output:
Found 5 ingredients:
- flour: 200 g
- sugar: 150 g
- butter: 100 g
- eggs: 2
- vanilla: 1 tsp

func (*Recipe) GetMetricShoppingList ¶

func (r *Recipe) GetMetricShoppingList() (map[string]string, error)

GetMetricShoppingList returns a shopping list with all ingredients converted to metric units. This is a convenience method for GetShoppingListInSystem(UnitSystemMetric).

Returns:

• map[string]string: A map of ingredient names to quantities (e.g., "flour": "500 g")
• error: Any error encountered during conversion

Example:

recipe, _ := cooklang.ParseFile("cookies.cook")
shoppingList, err := recipe.GetMetricShoppingList()
if err == nil {
    for ingredient, amount := range shoppingList {
        fmt.Printf("%s: %s\n", ingredient, amount)
    }
}

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @flour{2%cup} and @butter{4%oz}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	metricList, err := recipe.GetMetricShoppingList()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Metric shopping list:")
	// Print in deterministic order
	fmt.Printf("- butter: %s\n", metricList["butter"])
	fmt.Printf("- flour: %s\n", metricList["flour"])
}

Output:
Metric shopping list:
- butter: 113.4 g
- flour: 473.2 ml

func (*Recipe) GetShoppingListInSystem ¶

func (r *Recipe) GetShoppingListInSystem(system UnitSystem) (map[string]string, error)

GetShoppingListInSystem returns a shopping list with ingredients converted to the target unit system. The ingredients are first converted, then consolidated by name to combine duplicate entries.

Parameters:

• system: The target unit system (UnitSystemMetric, UnitSystemUS, UnitSystemImperial)

Returns:

• map[string]string: A map of ingredient names to formatted quantities
• error: Any error encountered during conversion

Example:

recipe, _ := cooklang.ParseFile("pasta.cook")
usList, _ := recipe.GetShoppingListInSystem(cooklang.UnitSystemUS)
for name, qty := range usList {
    fmt.Printf("%s: %s\n", name, qty)
}

func (*Recipe) GetUSShoppingList ¶

func (r *Recipe) GetUSShoppingList() (map[string]string, error)

GetUSShoppingList returns a shopping list with all ingredients converted to US customary units. Common conversions include: cups, tablespoons, teaspoons, ounces, pounds.

Returns:

• map[string]string: A map of ingredient names to quantities (e.g., "flour": "2 cup")
• error: Any error encountered during conversion

Example:

recipe, _ := cooklang.ParseFile("cookies.cook")
shoppingList, err := recipe.GetUSShoppingList()

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Add @water{500%ml} and @flour{250%g}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	usList, err := recipe.GetUSShoppingList()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("US shopping list:")
	// Print in deterministic order
	fmt.Printf("- flour: %s\n", usList["flour"])
	fmt.Printf("- water: %s\n", usList["water"])
}

Output:
US shopping list:
- flour: 8.8 oz
- water: 2.1 cup

func (*Recipe) Render ¶

func (r *Recipe) Render() string

Render returns a human-readable representation of the recipe. If a custom renderer has been set via SetRenderer or SetRendererFunc, it will be used. Otherwise, a default text format is used showing metadata, ingredients, and steps.

Example:

recipe, _ := cooklang.ParseFile("lasagna.cook")
fmt.Println(recipe.Render())

package main

import (
	"fmt"
	"log"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `---
title: Quick Snack
servings: 1
---
Toast @bread{2%slices} and spread @butter{1%tbsp}.`

	recipe, err := cooklang.ParseString(recipeText)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Recipe: %s (serves %.0f)\n", recipe.Title, recipe.Servings)
}

Output:
Recipe: Quick Snack (serves 1)

func (*Recipe) RenderWith ¶

func (r *Recipe) RenderWith(renderer RecipeRenderer) string

RenderWith renders the recipe using the provided renderer. This allows one-time rendering without setting a permanent renderer on the recipe.

Parameters:

• renderer: A RecipeRenderer implementation to use for rendering

Returns:

• string: The rendered recipe in the format defined by the renderer

Example:

recipe, _ := cooklang.ParseFile("recipe.cook")
markdown := recipe.RenderWith(renderers.MarkdownRenderer{})
html := recipe.RenderWith(renderers.HTMLRenderer{})

func (*Recipe) Scale ¶ added in v0.3.0

func (r *Recipe) Scale(factor float64) *Recipe

Scale creates a new recipe with all ingredient quantities scaled by the given factor. This is useful for adjusting recipe servings or batch cooking. Timers, cookware, and instructions are copied unchanged. Ingredients with "some" quantity (-1) are not scaled.

The servings metadata is also updated if present.

Parameters:

• factor: The scaling factor (e.g., 2.0 for double, 0.5 for half)

Returns:

• *Recipe: A new recipe with scaled quantities

Example:

recipe, _ := cooklang.ParseFile("cookies.cook")
doubled := recipe.Scale(2.0)  // Double all quantities
halved := recipe.Scale(0.5)   // Half all quantities

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `---
title: Pancakes
servings: 2
---
Mix @flour{200%g} with @milk{300%ml} and @eggs{2}.`

	recipe, _ := cooklang.ParseString(recipeText)

	// Double the recipe
	doubled := recipe.Scale(2.0)

	fmt.Printf("Original servings: %.0f\n", recipe.Servings)
	fmt.Printf("Doubled servings: %.0f\n", doubled.Servings)

	// Show scaled ingredients
	ingredients := doubled.GetIngredients()
	for _, ing := range ingredients.Ingredients {
		if ing.Unit != "" {
			fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
		} else {
			fmt.Printf("- %s: %.0f\n", ing.Name, ing.Quantity)
		}
	}
}

Output:
Original servings: 2
Doubled servings: 4
- flour: 400 g
- milk: 600 ml
- eggs: 4

func (*Recipe) ScaleToServings ¶ added in v0.3.0

func (r *Recipe) ScaleToServings(targetServings float64) *Recipe

ScaleToServings creates a new recipe scaled to the target number of servings. If the recipe doesn't have servings specified, it assumes 1 serving.

Parameters:

• targetServings: The desired number of servings

Returns:

• *Recipe: A new recipe scaled to the target servings

Example:

recipe, _ := cooklang.ParseFile("cookies.cook") // 12 servings
scaled := recipe.ScaleToServings(24)            // Double the recipe

package main

import (
	"fmt"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `---
title: Cookies
servings: 12
---
Mix @flour{300%g}, @sugar{150%g}, and @butter{100%g}.`

	recipe, _ := cooklang.ParseString(recipeText)

	// Scale from 12 to 36 servings (triple)
	scaled := recipe.ScaleToServings(36)

	fmt.Printf("Original: %.0f servings\n", recipe.Servings)
	fmt.Printf("Scaled: %.0f servings\n", scaled.Servings)

	ingredients := scaled.GetIngredients()
	for _, ing := range ingredients.Ingredients {
		fmt.Printf("- %s: %.0f %s\n", ing.Name, ing.Quantity, ing.Unit)
	}
}

Output:
Original: 12 servings
Scaled: 36 servings
- flour: 900 g
- sugar: 450 g
- butter: 300 g

func (*Recipe) SetRenderer ¶

func (r *Recipe) SetRenderer(renderer RecipeRenderer)

SetRenderer allows setting a custom renderer for a recipe. Once set, calling Render() will use this custom renderer instead of the default.

Parameters:

• renderer: A RecipeRenderer implementation

Example:

recipe, _ := cooklang.ParseFile("recipe.cook")
recipe.SetRenderer(renderers.MarkdownRenderer{})
markdown := recipe.Render()

func (*Recipe) SetRendererFunc ¶

func (r *Recipe) SetRendererFunc(renderFunc func(*Recipe) string)

SetRendererFunc allows setting a custom renderer function for a recipe

func (*RecipeReference) GetNext ¶ added in v1.0.5

func (r *RecipeReference) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*RecipeReference) Render ¶ added in v1.0.5

func (r *RecipeReference) Render() string

Render returns a human-readable string representation of the recipe reference.

func (*RecipeReference) SetNext ¶ added in v1.0.5

func (r *RecipeReference) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (RendererFunc) RenderRecipe ¶

func (f RendererFunc) RenderRecipe(recipe *Recipe) string

RenderRecipe implements the RecipeRenderer interface for RendererFunc.

func (*Section) GetNext ¶ added in v0.3.0

func (s *Section) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Section) Render ¶ added in v0.3.0

func (s Section) Render() string

Render returns the Cooklang syntax representation of this section. Examples: "== Section Name =="

func (Section) RenderDisplay ¶ added in v0.3.0

func (s Section) RenderDisplay() string

RenderDisplay returns section name suitable for display.

func (*Section) SetNext ¶ added in v0.3.0

func (s *Section) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (*ShoppingList) Count ¶

func (sl *ShoppingList) Count() int

Count returns the number of unique ingredients in the shopping list.

Returns:

• int: The number of ingredients (0 if the list is empty or nil)

Example:

list, _ := cooklang.CreateShoppingList(recipe1, recipe2)
fmt.Printf("You need %d ingredients\n", list.Count())

func (*ShoppingList) Scale ¶

func (sl *ShoppingList) Scale(multiplier float64) *ShoppingList

Scale scales all ingredients in the shopping list by the given multiplier. This is useful when adjusting recipe servings or batch cooking. Ingredients with "some" quantity (-1) are not scaled.

Parameters:

• multiplier: The scaling factor (e.g., 2.0 for double, 0.5 for half)

Returns:

• *ShoppingList: A new shopping list with scaled quantities

Example:

shoppingList, _ := cooklang.CreateShoppingList(recipe)
doubled := shoppingList.Scale(2.0)  // Double all quantities
halved := shoppingList.Scale(0.5)   // Half all quantities

package main

import (
	"fmt"
	"sort"

	"github.com/hilli/cooklang"
)

func main() {
	recipeText := `Use @flour{200%g} and @sugar{100%g}.`

	recipe, _ := cooklang.ParseString(recipeText)
	shoppingList, _ := cooklang.CreateShoppingList(recipe)

	// Double the recipe
	scaled := shoppingList.Scale(2.0)

	fmt.Println("Scaled (×2):")
	scaledMap := scaled.ToMap()
	// Sort keys for consistent output
	keys := make([]string, 0, len(scaledMap))
	for name := range scaledMap {
		keys = append(keys, name)
	}
	sort.Strings(keys)

	for _, name := range keys {
		fmt.Printf("- %s: %s\n", name, scaledMap[name])
	}
}

Output:
Scaled (×2):
- flour: 400 g
- sugar: 200 g

func (*ShoppingList) ToMap ¶

func (sl *ShoppingList) ToMap() map[string]string

ToMap returns the shopping list as a map of ingredient names to formatted quantities. This is a convenience method that delegates to IngredientList.ToMap().

Returns:

• map[string]string: A map of ingredient names to quantity strings

Example:

list, _ := cooklang.CreateShoppingList(recipe1, recipe2)
for name, qty := range list.ToMap() {
    fmt.Printf("- %s: %s\n", name, qty)
}

func (*Step) HasDisplayableContent ¶ added in v1.0.0

func (s *Step) HasDisplayableContent() bool

HasDisplayableContent returns true if the step contains any content that should be displayed to users (ingredients, cookware, timers, non-whitespace text, sections, or notes). Steps containing only comments or whitespace-only text return false.

func (*Timer) GetNext ¶

func (t *Timer) GetNext() StepComponent

GetNext returns the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.

func (Timer) Render ¶

func (t Timer) Render() string

Render returns the Cooklang syntax representation of this timer. Examples: "~{10%minutes}", "~boil{15%min}"

func (Timer) RenderDisplay ¶

func (t Timer) RenderDisplay() string

RenderDisplay returns timer in plain text format suitable for display. Returns the duration with unit if available, or just the duration. If the timer has a name but no duration, returns the name.

func (*Timer) SetNext ¶

func (t *Timer) SetNext(next StepComponent)

SetNext sets the next component in the step's linked list. This implements the StepComponent interface for recipe step traversal.