fileutil

Documentation

Overview

Package fileutil provides utilities for interacting with a corgi AST and its contents.

Index

• Variables
• func Body(itm file.ScopeItem) (body file.Scope, has bool)
• func EqualFile(a, b *file.File) bool
• func EqualLibrary(a, b *file.Library) bool
• func FirstNonControl(s file.Scope) file.ScopeItem
• func IsAttrMixin(lm file.LinkedMixin) bool
• func IsElementMixin(lm file.LinkedMixin) bool
• func IsFirstNonControlAttr(s file.Scope) (file.ScopeItem, bool)
• func IsStdLibFile(f *file.File) bool
• func Quote(s file.String) string
• func Unquote(s file.String) string
• func UsePath(f *file.File) string
• func Walk(s file.Scope, f WalkFunc) error
• type MachineComment
  • func ParseMachineComment(c file.CorgiComment) *MachineComment
  • func ParseMachineCommentLine(ln string) MachineComment
• type UsedLibrary
• type UsedMixin
• type UsedMixins
  • func LibraryDependencies(lib *file.Library) UsedMixins
  • func ListUsedMixins(f *file.File) UsedMixins
• type WalkContext
• type WalkFunc

Variables

var StopWalk = errors.New("stop walk")

StopWalk can be returned from a WalkFunc to indicate that Walk should return immediately, but without actually returning an error.

Functions

func Body

func Body(itm file.ScopeItem) (body file.Scope, has bool)

Body returns the body of itm and true, if it has one, or nil and false, if it does not.

For file.If and file.IfBlock it returns Then, and for file.Switch it returns (nil, false).

func EqualFile

func EqualFile(a, b *file.File) bool

func EqualLibrary

func EqualLibrary(a, b *file.Library) bool

func FirstNonControl

func FirstNonControl(s file.Scope) file.ScopeItem

FirstNonControl returns the first non-if, if block, switch and for item in the given scope.

This means it either returns nil for an empty scope, s[0] for a scope that doesn't start with a control directive, or the first non-control item nested inside the control item at s[0].

func IsAttrMixin

func IsAttrMixin(lm file.LinkedMixin) bool

func IsElementMixin

func IsElementMixin(lm file.LinkedMixin) bool

func IsFirstNonControlAttr

func IsFirstNonControlAttr(s file.Scope) (file.ScopeItem, bool)

func IsStdLibFile

func IsStdLibFile(f *file.File) bool

func Quote

func Quote(s file.String) string

Quote returns the file.String in quotes, as it was written in the file.

func Unquote

func Unquote(s file.String) string

Unquote unquotes the passed file.String. If the passed string is not syntactically valid, Unquote returns an empty string.

func UsePath

func UsePath(f *file.File) string

UsePath returns the path needed to use this file.

It correctly accounts for files from corgi's standard library.

func Walk

func Walk(s file.Scope, f WalkFunc) error

Walk wals the passed scope in depth-first order, calling f for each item it encounters.

If an item has a body and f returns true, Walk will dive into it, walking it as well.

If it dives conditionals, it walks all branches. Branches may be distinguished by the appropriate fields of the passed WalkContext.

Walk calls f with a slice of ctx.Item's parents. That slice is reused for each call to f, and should not be retained after f exits.

Types

type MachineComment

type MachineComment struct {
	Namespace string
	Directive string
	Args      string
}

MachineComment represents a corgi comment intended for machines. It follows the same semantics as a Go machine comments, namely a comments whose text is NOT separated from the `//` by any whitespace.

Each machine comment starts with a namespace and an optional directive, separated from the namespace by a colon. It is followed by optional args, separated by a space from the namespace/directive.

func ParseMachineComment

func ParseMachineComment(c file.CorgiComment) *MachineComment

ParseMachineComment attempts to parse the passed file.CorgiComment as a machine comment.

If it is not, ParseMachineComment returns nil.

func ParseMachineCommentLine

func ParseMachineCommentLine(ln string) MachineComment

type UsedLibrary

type UsedLibrary struct {
	// Library is the library that is being referenced.
	Library *file.Library

	Mixins []UsedMixin
}

type UsedMixin

type UsedMixin struct {
	Mixin *file.Mixin

	// RequiredBy lists the mixins requiring this mixin in the library
	// being analyzed.
	//
	// Only present/valid for [LibraryDependencies].
	RequiredBy []string
}

type UsedMixins

type UsedMixins struct {
	// External lists all used mixins from library files.
	//
	// If LibraryDependencies was called, only direct dependencies will be
	// included here.
	External []UsedLibrary

	// Self lists all mixins from the calling library that are used by it.
	//
	// It is only present for calls to [LibraryDependencies].
	Self []UsedMixin
}

UsedMixins lists all mixins used by a given file, if it were printed.

Depending on whether ListUsedMixins LibraryDependencies was called, some fields might not be set.

func LibraryDependencies

func LibraryDependencies(lib *file.Library) UsedMixins

func ListUsedMixins

func ListUsedMixins(f *file.File) UsedMixins

type WalkContext

type WalkContext struct {
	// Scope is the scope in which the item was found.
	Scope file.Scope
	// Index is the index of the item.
	Index int
	// Item is a pointer to the item, allowing it to be edited.
	Item *file.ScopeItem

	// Case is the case of Item.(file.Switch) that we are walking.
	//
	// Note that if this is set, the parent context's item will be the switch's
	// parent, not the switch itself.
	Case *file.Case
	// ElseIf is the else if of Item.(file.If) or Item.(file.IfBlock) that we
	// are walking.
	//
	// Note that if this is set, the parent context's item will be if's
	// parent, not the if itself.
	ElseIf *file.ElseIf
	// ElseIfBlock is the else if of Item.(file.IfBlock) that we are walking.
	//
	// Note that if this is set, the parent context's item will be if's
	// parent, not the if itself.
	ElseIfBlock *file.ElseIfBlock
	// Else is the else of Item.(file.If) that we are walking.
	//
	// Note that if this is set, the parent context's item will be if's
	// parent, not the if itself.
	Else *file.Else

	// Comments are the corgi comments preceding the item.
	Comments []file.CorgiComment
}

type WalkFunc

type WalkFunc func(parents []WalkContext, ctx WalkContext) (dive bool, err error)