nav

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2024 License: MIT Imports: 26 Imported by: 5

Documentation

Index

Constants

View Source 
const (
	JSONMarshallNoPrefix      = ""
	JSONMarshall2SpacesIndent = "  "
)
View Source 
const (
	MinNoWorkers = 1
	MaxNoWorkers = 100
)

Variables

View Source 
var BenignNodeFilterDef = FilterDef{
	Type:        FilterTypeRegexEn,
	Description: "benign allow all",
	Pattern:     ".",
	Scope:       ScopeRootEn,
}
View Source 
var ErrUndefinedSubscriptionType = errors.New(
	"undefined subscription type; please set in traverse options (/Options.Store.Subscription)",
)

ErrUndefinedSubscriptionType indicates client has not set the navigation subscription type at /Options.Store.Subscription.

Functions

func CaseInSensitiveSortHookFn 

func CaseInSensitiveSortHookFn(entries []fs.DirEntry, _ ...any) error

CaseInSensitiveSortHookFn hook function for case insensitive directory traversal. A directory of "a" will be visited before a sibling directory "B".

func CaseSensitiveSortHookFn 

func CaseSensitiveSortHookFn(entries []fs.DirEntry, _ ...any) error

CaseSensitiveSortHookFn hook function for case sensitive directory traversal. A directory of "a" will be visited after a sibling directory "B".

func CreateTraverseOutputCh added in v0.2.0 

func CreateTraverseOutputCh(outputChSize int) boost.JobOutputStream[TraverseOutput]

func DefaultExtendHookFn 

func DefaultExtendHookFn(navi *NavigationInfo, entries *DirectoryContents)

DefaultExtendHookFn is the default extend hook function. The client can choose to override this by setting the custom function on options.Hooks.Extend. If the client wishes to augment the default behaviour rather than replace it, they can call this function from inside the custom function.

func IfWithPoolUseContext added in v0.2.1 

func IfWithPoolUseContext(with CreateNewRunnerWith, args ...any) []any

func InitFiltersHookFn 

func InitFiltersHookFn(o *TraverseOptions, frame *navigationFrame)

InitFiltersHookFn is the default filter initialiser. This can be overridden or extended by the client if the need arises. To extend this behaviour rather than replace it, call this function from inside the custom function set on o.Hooks.Filter. To replace the default functionality, do note the following points: - the original client callback is defined as frame.client, this should be referred to from outside the custom function (ie in the closure) as is performed here in the default. This will allow the custom function to invoke the core callback as appropriate. - The filters defined here in extendio make use of some extended fields, so if the client needs to define a custom function that is compatible with the native filters, then make sure the DoExtend value is set to true in the options, otherwise a panic will occur due to the filter attempting to de-reference the Extension on the TraverseItem.

func LstatHookFn 

func LstatHookFn(path string) (fs.FileInfo, error)

Lstat is the default Query Status hook function

func NewInvalidNotificationMuteRequestedNativeError 

func NewInvalidNotificationMuteRequestedNativeError(value string) error

NewInvalidNotificationMuteRequestedNativeError creates an untranslated error to indicate invalid notification mute requested (internal error)

func NewInvalidPeriscopeRootPathNativeError 

func NewInvalidPeriscopeRootPathNativeError(root, current string) error

NewInvalidPeriscopeRootPathNativeError creates an untranslated error to indicate invalid resume state transition occurred (internal error)

func NewInvalidResumeStateTransitionNativeError 

func NewInvalidResumeStateTransitionNativeError(state string) error

NewItemAlreadyExtendedNativeError creates an untranslated error to indicate invalid resume state transition occurred (internal error)

func NewItemAlreadyExtendedNativeError 

func NewItemAlreadyExtendedNativeError(path string) error

NewItemAlreadyExtendedNativeError creates an untranslated error to indicate traverse-item already extended (internal error)

func NewMissingListenDetacherFunctionNativeError 

func NewMissingListenDetacherFunctionNativeError(state string) error

NewMissingListenDetacherFunctionNativeError creates an untranslated error to indicate invalid resume state transition occurred (internal error)

func NewResumeControllerNotSetNativeError 

func NewResumeControllerNotSetNativeError(from string) error

NewResumeControllerNotSetNativeError creates an untranslated error to indicate resume controller not set (internal error)

func ReadEntriesHookFn added in v0.4.0 

func ReadEntriesHookFn(dirname string) ([]fs.DirEntry, error)

ReadEntriesHookFn reads the contents of a directory. The resulting slice is left un-sorted

func RootItemSubPathHookFn added in v0.4.0 

func RootItemSubPathHookFn(info *SubPathInfo) string

RootItemSubPathHookFn

func RootParentSubPathHookFn added in v0.4.0 

func RootParentSubPathHookFn(info *SubPathInfo) string

RootParentSubPathHookFn

func Tail 

func Tail(input string, offset int) string

Tail extracts the end part of a string, starting from the offset

Types

type Acceleration added in v0.2.1 

type Acceleration struct {
	WgAn            boost.WaitGroupAn
	RoutineName     boost.GoRoutineName
	NoW             int
	JobsChOut       TraverseItemJobStream
	JobResultsCh    boost.JobOutputStream[TraverseOutput]
	OutputChTimeout time.Duration
}

type AccelerationOperators added in v0.2.0 

type AccelerationOperators interface {
	Runnable
	NoW(now int) AccelerationOperators
	Consume(outputCh boost.JobOutputStream[TraverseOutput], timeout time.Duration) AccelerationOperators
}

type ActiveState 

type ActiveState struct {
	Root     string
	Listen   ListeningState
	NodePath string
	Depth    int
	Metrics  *MetricCollection
}

type AscendancyHandler 

type AscendancyHandler func(item *TraverseItem)

AscendancyHandler defines the signatures of ascend/descend handlers

type AsyncInfo added in v0.2.0 

type AsyncInfo struct {
	// this doesn't seem right, the client shouldn't have to specify
	// the routine name for the navigator; should be a readonly prop
	// of the navigator. Perhaps, it can be overridden by the user
	// here, but the navigator should have an internally defined default.
	//
	NavigatorRoutineName boost.GoRoutineName
	WaitAQ               boost.AnnotatedWgAQ

	// why are we passing in the jobs output channel here, rather than...
	// (perhaps a new operator, like how Consume() op takes the outputCh?)
	// The difference here though is that JobsChanOut is mandatory but
	// Consume & outputCh are optional.
	//
	JobsChanOut TraverseItemJobStream
}

type BeginHandler 

type BeginHandler func(ns *NavigationState)

BeginHandler life cycle event handler, invoked before start of traversal

type CascadeBehaviour added in v0.5.2 

type CascadeBehaviour struct {
	// Depth sets a maximum traversal depth
	//
	Depth uint

	// NoRecurse is an alternative to using Depth, but limits the traversal
	// to just the path specified by the user. Since the raison d'etre
	// of the navigator is to recursively process a directory tree, using
	// NoRecurse would appear to be contrary to its natural behaviour. However
	// there are clear usage scenarios where a client needs to process
	// only the files in a specified directory.
	//
	NoRecurse bool
}

type CompoundExtendedGlobFilter added in v0.5.4 

type CompoundExtendedGlobFilter struct {
	CompoundFilter
	// contains filtered or unexported fields
}

func (*CompoundExtendedGlobFilter) Matching added in v0.5.4 

func (f *CompoundExtendedGlobFilter) Matching(children []fs.DirEntry) []fs.DirEntry

type CompoundFilter 

type CompoundFilter struct {
	Name    string
	Pattern string
	Negate  bool
}

CompoundFilter filter used when subscription is FoldersWithFiles

func (*CompoundFilter) Description 

func (f *CompoundFilter) Description() string

func (*CompoundFilter) Source 

func (f *CompoundFilter) Source() string

func (*CompoundFilter) Validate 

func (f *CompoundFilter) Validate()

type CompoundFilterDef 

type CompoundFilterDef struct {
	// Type specifies the type of filter (mandatory)
	Type FilterTypeEnum

	// Description describes filter (optional)
	Description string

	// Pattern filter definition (mandatory)
	Pattern string

	// Negate, reverses the applicability of the filter (Defaults to false)
	Negate bool

	// Custom client define-able filter. When restoring for resume feature,
	// its the client's responsibility to restore this themselves (see
	// PersistenceRestorer)
	Custom CompoundTraverseFilter `json:"-"`
}

type CompoundGlobFilter 

type CompoundGlobFilter struct {
	CompoundFilter
}

func (*CompoundGlobFilter) Matching 

func (f *CompoundGlobFilter) Matching(children []fs.DirEntry) []fs.DirEntry

Matching returns the collection of files contained within this item's folder that matches this filter.

type CompoundRegexFilter 

type CompoundRegexFilter struct {
	CompoundFilter
	// contains filtered or unexported fields
}

func (*CompoundRegexFilter) Matching 

func (f *CompoundRegexFilter) Matching(children []fs.DirEntry) []fs.DirEntry

func (*CompoundRegexFilter) Validate 

func (f *CompoundRegexFilter) Validate()

type CompoundTraverseFilter 

type CompoundTraverseFilter interface {
	// Description describes filter
	Description() string

	// Validate ensures the filter definition is valid, panics when invalid
	Validate()

	// Source, filter definition (comes from filter definition Pattern)
	Source() string

	// Matching returns the collection of files contained within this
	// item's folder that matches this filter.
	Matching(children []fs.DirEntry) []fs.DirEntry
}

CompoundTraverseFilter filter that can be applied to a folder's collection of entries when subscription is

type CreateNewRunnerWith added in v0.2.1 

type CreateNewRunnerWith int
const (
	RunnerDefault    CreateNewRunnerWith = 0
	RunnerWithResume CreateNewRunnerWith = 1
	RunnerWithPool   CreateNewRunnerWith = 2
)

type DirectoryContents added in v0.4.0 

type DirectoryContents struct {
	Options *TraverseOptions
	Folders []fs.DirEntry
	Files   []fs.DirEntry
}

DirectoryContents represents the contents of a directory's contents and handles sorting order which by default is different between various operating systems. This abstraction removes the differences in sorting behaviour on different platforms.

func (*DirectoryContents) All added in v0.4.0 

func (e *DirectoryContents) All() []fs.DirEntry

All returns the contents of a directory respecting the directory sorting order defined in the traversal options.

type DirectoryContentsOrderEnum added in v0.4.0 

type DirectoryContentsOrderEnum uint

DirectoryContentsOrderEnum determines what order a directories entries are invoked for. 

const (
	// DirectoryContentsOrderFoldersFirstEn invoke folders first
	DirectoryContentsOrderFoldersFirstEn DirectoryContentsOrderEnum = iota

	// DirectoryContentsOrderFilesFirstEn invoke files first
	DirectoryContentsOrderFilesFirstEn
)

type EachDirectoryItemPredicate added in v0.4.0 

type EachDirectoryItemPredicate func(childItem *TraverseItem) bool

EachDirectoryItemPredicate callback to invoke for each child item

type EndHandler 

type EndHandler func(result *TraverseResult)

EndHandler life cycle event handler, invoked at end of traversal

type EnoughAlready added in v0.4.0 

type EnoughAlready struct {
	Files   bool
	Folders bool
}

EnoughAlready when using the universal navigator within a sampling operation, set these accordingly from inside the while predicate to indicate wether the iteration loop should continue to consider more entries to be included in the sample. So set Files/Folders flags to true, when enough of those items have been included.

type EntryQuantities added in v0.4.0 

type EntryQuantities struct {
	Files   uint
	Folders uint
}

EntryQuantities contains specification of no of files and folders used in various contexts, but primarily sampling.

type ExtendHookFn 

type ExtendHookFn func(navi *NavigationInfo, entries *DirectoryContents)

ExtendHookFn

type ExtendedGlobFilter added in v0.5.4 

type ExtendedGlobFilter struct {
	Filter
	// contains filtered or unexported fields
}

func (*ExtendedGlobFilter) IsMatch added in v0.5.4 

func (f *ExtendedGlobFilter) IsMatch(item *TraverseItem) bool

IsMatch does this item match the filter

type ExtendedItem 

type ExtendedItem struct {
	Depth     int               // traversal depth relative to the root
	IsLeaf    bool              // defines whether this node a leaf node
	Name      string            // derived as the leaf segment from filepath.Split
	Parent    string            // derived as the directory from filepath.Split
	SubPath   string            // represents the path between the root and the current item
	NodeScope FilterScopeBiEnum // type of folder corresponding to the Filter Scope
	Custom    any               // to be set and used by the client
}

ExtendedItem provides extended information if the client requests it by setting the DoExtend boolean in the traverse options.

type Filter 

type Filter struct {
	// contains filtered or unexported fields
}

Filter base filter struct.

func (*Filter) Description 

func (f *Filter) Description() string

Description description of the filter

func (*Filter) IsApplicable 

func (f *Filter) IsApplicable(item *TraverseItem) bool

func (*Filter) Scope 

func (f *Filter) Scope() FilterScopeBiEnum

func (*Filter) Source 

func (f *Filter) Source() string

Source text defining the filter

func (*Filter) Validate 

func (f *Filter) Validate()

type FilterDef 

type FilterDef struct {
	// Type specifies the type of filter (mandatory)
	Type FilterTypeEnum

	// Description describes filter (optional)
	Description string

	// Pattern filter definition (mandatory)
	Pattern string

	// Scope which file system entries this filter applies to (defaults
	// to ScopeAllEn)
	Scope FilterScopeBiEnum

	// Negate, reverses the applicability of the filter (Defaults to false)
	Negate bool

	// IfNotApplicable, when the filter does not apply to a directory entry,
	// this value determines whether the callback is invoked for this entry
	// or not (defaults to TriStateBoolTrueEn/true).
	IfNotApplicable TriStateBoolEnum

	// Custom client define-able filter. When restoring for resume feature,
	// its the client's responsibility to restore this themselves (see
	// PersistenceRestorer)
	Custom TraverseFilter `json:"-"`

	// Poly allows for the definition of a PolyFilter which contains separate
	// filters that target files and folders separately. If present, then
	// all other fields are redundant, since the filter definitions inside
	// Poly should be referred to instead.
	Poly *PolyFilterDef
}

FilterDef defines a filter to be used filtering or listening features.

type FilterDefinitions 

type FilterDefinitions struct {
	// Node denotes the filter object that represents the current file system item
	// being visited.
	//
	Node FilterDef

	// Children denotes the compound filter that is applied to the direct descendants
	// of the current file system item being visited.
	//
	Children CompoundFilterDef
}

type FilterInitHookFn 

type FilterInitHookFn func(o *TraverseOptions, frame *navigationFrame)

FilterInitHookFn

type FilterScopeBiEnum 

type FilterScopeBiEnum uint32

FilterScopeBiEnum allows client to define which node types should be filtered. Filters can be applied to multiple node types by bitwise or-ing the XXXNodes definitions. A node may have multiple scope designations, eg a node may be top level and leaf if the top level directory does not itself contain further sub-directories thereby making it also a leaf. It should be noted a file is only a leaf node all of its siblings are all files only 

const (
	ScopeUndefinedEn FilterScopeBiEnum = 0

	// ScopeRootEn, the Root scope
	//
	ScopeRootEn FilterScopeBiEnum = 1 << (iota - 1)

	// ScopeTopEn, any node that is a direct descendent of the root node
	//
	ScopeTopEn

	// ScopeLeafEn, for directories, any node that has no sub folders. For files, any node
	// that appears under a leaf directory node
	//
	ScopeLeafEn

	// ScopeIntermediateEn, apply filter to nodes which are neither leaf or top nodes
	//
	ScopeIntermediateEn

	// ScopeFileEn attributed to file nodes
	//
	ScopeFileEn

	// ScopeFolderEn attributed to directory nodes
	//
	ScopeFolderEn

	// ScopeCustomEn, client defined categorisation (yet to be confirmed)
	//
	ScopeCustomEn

	// ScopeAllEn represents any node type
	//
	ScopeAllEn = math.MaxUint32
)

func (*FilterScopeBiEnum) Clear added in v0.5.1 

func (f *FilterScopeBiEnum) Clear(mask FilterScopeBiEnum)

Clear clears the bit position indicated by mask

func (*FilterScopeBiEnum) Set added in v0.5.1 

func (f *FilterScopeBiEnum) Set(mask FilterScopeBiEnum)

Set sets the bit position indicated by mask

func (FilterScopeBiEnum) String 

func (f FilterScopeBiEnum) String() string

String converts enum value to a string

type FilterTypeEnum 

type FilterTypeEnum uint
const (
	FilterTypeUndefinedEn FilterTypeEnum = iota

	// FilterTypeExtendedGlobEn is the preferred filter type as it the most
	// user friendly. The base part of the name is filtered by a glob
	// and the suffix is filtered by a list of defined extensions. The pattern
	// for the extended filter type is composed of 2 parts; the first is a
	// glob, which is applied to the base part of the name. The second part
	// is a csv of required extensions to filter for. The pattern is specified
	// in the form: "<base-glob>|ext1,ext2...". Each extension may include a
	// a leading dot. An example pattern definition would be:
	// "cover.*|.jpg,jpeg"
	FilterTypeExtendedGlobEn

	// FilterTypeRegexEn regex filter
	FilterTypeRegexEn

	// FilterTypeGlobEn glob filter
	FilterTypeGlobEn

	// FilterTypeCustomEn client definable filter
	FilterTypeCustomEn

	// FilterTypePolyEn poly filter
	FilterTypePolyEn
)

type FilteredInfo added in v0.4.0 

type FilteredInfo struct {
	Counts EntryQuantities
	Enough EnoughAlready
}

FilteredInfo used within the sampling process during a traversal; more specifically, they should be set inside the while predicate. Note, the Enough field is only appropriate when using the universal navigator.

type GlobFilter 

type GlobFilter struct {
	Filter
}

GlobFilter wildcard filter.

func (*GlobFilter) IsMatch 

func (f *GlobFilter) IsMatch(item *TraverseItem) bool

IsMatch does this item match the filter

type LabelledTraverseCallback 

type LabelledTraverseCallback struct {
	Label string
	Fn    TraverseCallback
}

type ListenBehaviour 

type ListenBehaviour struct {
	InclusiveStart bool
	InclusiveStop  bool
}

type ListenDefinitions 

type ListenDefinitions struct {
	// Node denotes the filter object that represents the current file system item
	// being visited.
	//
	StartAt *FilterDef
	StopAt  *FilterDef
}

type ListenHandler 

type ListenHandler func(description string)

ListenHandler

type ListenTriggers 

type ListenTriggers struct {
	Start TraverseFilter
	Stop  TraverseFilter
}

ListenTriggers

type ListeningState 

type ListeningState uint

ListeningState denotes whether user defined callback is being invoked. 

const (
	ListenUndefined ListeningState = iota
	ListenDeaf                     // listen not active, callback always invoked (subject to filtering)
	ListenFastward                 // listen used to resume by fast-forwarding
	ListenPending                  // conditional listening is awaiting activation
	ListenActive                   // conditional listening is active (callback is invoked)
	ListenRetired                  // conditional listening is now deactivated
)

type LogRotationOptions 

type LogRotationOptions struct {
	// MaxSizeInMb, max size of a log file, before it is re-cycled
	MaxSizeInMb int

	// MaxNoOfBackups, max number of legacy log files that can exist
	// before being deleted
	MaxNoOfBackups int

	// MaxAgeInDays, max no of days before old log file is deleted
	MaxAgeInDays int
}

type Metric 

type Metric struct {
	Name  string
	Count uint
}

Metric

type MetricCollection 

type MetricCollection map[MetricEnum]*Metric

MetricCollection TODO: make this private as it's internal implementation detail

type MetricEnum 

type MetricEnum uint
const (
	// MetricNoFilesInvokedEn represents the no of files invoked for during traversal
	//
	MetricNoFilesInvokedEn MetricEnum = iota

	// MetricNoFilesFilteredOutEn represents the no of files filtered out
	//
	MetricNoFilesFilteredOutEn

	// MetricNoFoldersInvokedEn represents the no of folders invoked for during traversal
	//
	MetricNoFoldersInvokedEn

	// MetricNoFoldersFilteredOutEn represents the no of folders filtered out
	//
	MetricNoFoldersFilteredOutEn

	// MetricNoChildFilesFoundEn represents the number of children files
	// of a particular directory that pass the compound filter when using the folders
	// with files subscription
	//
	MetricNoChildFilesFoundEn

	// MetricNoChildFilesFilteredOutEn represents the number of children files
	// of a particular directory that fail to pass the compound filter when using
	// the folders with files subscription
	//
	MetricNoChildFilesFilteredOutEn
)

if new metrics are added, ensure that navigationMetricsFactory.new is kept in sync.

type MonitorOptions added in v0.5.3 

type MonitorOptions struct {
	Log *slog.Logger
}
type NavigationBehaviours struct {
	// SubPath, behaviours relating to handling of sub-path calculation
	//
	SubPath SubPathBehaviour

	// Sort, behaviours relating to sorting of a folder's directory entries.
	//
	Sort SortBehaviour

	// Listen, behaviours relating to listen functionality.
	//
	Listen ListenBehaviour

	// Cascade controls how deep to navigate
	//
	Cascade CascadeBehaviour
}

NavigationBehaviours 

type NavigationFilters struct {
	// Node denotes the filter object that represents the Node file system item
	// being visited.
	//
	Node TraverseFilter

	// Children denotes the Compound filter that is applied to the direct descendants
	// of the current file system item being visited.
	//
	Children CompoundTraverseFilter
}
type NavigationInfo struct {
	Options *TraverseOptions
	Item    *TraverseItem
	// contains filtered or unexported fields
}

NavigationInfo 

type NavigationMetrics struct {
	// contains filtered or unexported fields
}
func (m *NavigationMetrics) Count(metricEn MetricEnum) uint
type NavigationRunner interface {
	AccelerationOperators
	WithPool(ai *AsyncInfo) AccelerationOperators
	Save(path string) error
}
type NavigationState struct {
	Root    *utils.VarProp[string]
	Filters *NavigationFilters
	Logger  *slog.Logger
}

NavigationState carries information about navigation that client may be interested in and permitted to access, as opposed to the navigationFrame which is meant for internal purposes only. 

type NavigationSync interface {
	Run(callback sessionCallback, nc syncable, args ...any) (*TraverseResult, error)
}

type Notifications 

type Notifications struct {
	// OnBegin invoked at beginning of traversal
	///
	OnBegin BeginHandler

	// OnEnd invoked at end of traversal
	//
	OnEnd EndHandler

	// OnDescend handler to invoke as a folder is descended (before children)
	//
	OnDescend AscendancyHandler

	// OnAscend handler to invoke as a folder is ascended (after children)
	OnAscend AscendancyHandler

	// OnStart handler invoked when start listening condition met if enabled
	//
	OnStart ListenHandler

	// OnStop handler invoked when finish listening condition met if enabled
	//
	OnStop ListenHandler
}

Notifications

type OptionsStore 

type OptionsStore struct {
	// Subscription defines which node types are visited
	//
	Subscription TraverseSubscription

	// Behaviours collection of behaviours that adjust the way navigation occurs,
	// that can be tweaked by the client.
	//
	Behaviours NavigationBehaviours

	// FilterDefs definitions of filters that restricts for which file system nodes the
	// Callback is invoked for.
	//
	FilterDefs *FilterDefinitions

	// ListenDefs definitions to define when listening starts and stops. Filters
	// can be used to define the Listeners.
	//
	ListenDefs ListenDefinitions

	// Sampling options
	//
	Sampling SamplingOptions
}

OptionsStore represents that part of options that is directly persist-able.

type PersistCompoundFilterDef 

type PersistCompoundFilterDef struct {
	Description string
	Source      string
}

type PersistFilterDef 

type PersistFilterDef struct {
	Description string
	Source      string
	Scope       FilterScopeBiEnum
}

type PersistFilters 

type PersistFilters struct {
	Node     *PersistFilterDef
	Children *PersistCompoundFilterDef
}

type PersistOptions 

type PersistOptions struct {
	Format PersistenceFormatEnum
}

PersistOptions contains options for persisting traverse options

type PersistenceFormatEnum 

type PersistenceFormatEnum uint
const (
	PersistInUndefinedEn PersistenceFormatEnum = iota
	PersistInJSONEn
)

type PersistenceRestorer 

type PersistenceRestorer func(o *TraverseOptions, active *ActiveState)

type PolyFilter added in v0.5.1 

type PolyFilter struct {
	// File is the filter that applies to a file. Note that the client does
	// not have to set the File scope as this is enforced automatically as
	// well as ensuring that the Folder scope has not been set. The client is
	// still free to set other scopes.
	File TraverseFilter

	// Folder is the filter that applies to a folder. Note that the client does
	// not have to set the Folder scope as this is enforced automatically as
	// well as ensuring that the File scope has not been set. The client is
	// still free to set other scopes.
	Folder TraverseFilter
}

PolyFilter is a dual filter that allows files and folders to be filtered independently. The Folder filter only applies when the current item is a file. This is because, filtering doesn't affect navigation, it only controls wether the client callback is invoked or not. That is to say, if a particular folder fails to pass a filter, the callback will not be invoked for that folder, but we still descend into it and navigate its children. This is the reason why the poly filter is only active when the the current item is a filter as the client callback will only be invoked for the file if its parent folder passes the poly folder filter and the file passes the poly file filter.

func (*PolyFilter) Description added in v0.5.1 

func (f *PolyFilter) Description() string

Description

func (*PolyFilter) IsApplicable added in v0.5.1 

func (f *PolyFilter) IsApplicable(item *TraverseItem) bool

IsApplicable returns the result of applying IsApplicable to the poly Filter filter if the current item is a file, returns false for folders.

func (*PolyFilter) IsMatch added in v0.5.1 

func (f *PolyFilter) IsMatch(item *TraverseItem) bool

IsMatch returns true if the current item is a file and both the current file matches the poly file filter and the file's parent folder matches the poly folder filter. Returns true of the current item is a folder.

func (*PolyFilter) Scope added in v0.5.1 

func (f *PolyFilter) Scope() FilterScopeBiEnum

Scope is a bitwise OR combination of both filters

func (*PolyFilter) Source added in v0.5.1 

func (f *PolyFilter) Source() string

Source returns the Sources of both the File and Folder filters separated by a '##'

func (*PolyFilter) Validate added in v0.5.1 

func (f *PolyFilter) Validate()

Validate ensures that both filters definition are valid, panics when invalid

type PolyFilterDef added in v0.5.1 

type PolyFilterDef struct {
	File   FilterDef
	Folder FilterDef
}

type Primary added in v0.2.0 

type Primary struct {
	Path            string
	OptionFn        TraverseOptionFn
	ProvidedOptions *TraverseOptions
	// contains filtered or unexported fields
}

Primary

func (*Primary) Elapsed added in v0.2.0 

func (s *Primary) Elapsed() time.Duration

func (*Primary) Save added in v0.2.0 

func (s *Primary) Save(path string) error

Save persists the current state for a primary session, that allows a subsequent run to complete the resume.

func (*Primary) StartedAt added in v0.2.0 

func (s *Primary) StartedAt() time.Time

type Prime added in v0.2.0 

type Prime struct {
	Path            string
	OptionsFn       TraverseOptionFn
	ProvidedOptions *TraverseOptions
}

type QueryStatusHookFn 

type QueryStatusHookFn func(path string) (fs.FileInfo, error)

Lstat function signature that enables the default t be overridden

type ReadDirectoryHookFn 

type ReadDirectoryHookFn func(dirname string) ([]fs.DirEntry, error)

ReadDirectoryHookFn hook function to define implementation of how a directory's entries are read. A default implementation is preset, so does not have to be set by the client.

type RegexFilter 

type RegexFilter struct {
	Filter
	// contains filtered or unexported fields
}

RegexFilter regex filter.

func (*RegexFilter) IsMatch 

func (f *RegexFilter) IsMatch(item *TraverseItem) bool

IsMatch

func (*RegexFilter) Validate 

func (f *RegexFilter) Validate()

Validate ensures the filter definition is valid, panics when invalid

type Resume added in v0.2.0 

type Resume struct {
	RestorePath string
	Restorer    func(o *TraverseOptions, active *ActiveState)
	Strategy    ResumeStrategyEnum
	// contains filtered or unexported fields
}

Resume represents a traversal that is invoked as a result of the user needing to resume a previously interrupted navigation session.

func (*Resume) Elapsed added in v0.2.0 

func (s *Resume) Elapsed() time.Duration

func (*Resume) Save added in v0.2.0 

func (s *Resume) Save(path string) error

Save persists the current state for a resume session, that allows a subsequent run to complete the resume.

func (*Resume) StartedAt added in v0.2.0 

func (s *Resume) StartedAt() time.Time

type ResumeStrategyEnum 

type ResumeStrategyEnum uint
const (
	ResumeStrategyUndefinedEn ResumeStrategyEnum = iota
	ResumeStrategySpawnEn
	ResumeStrategyFastwardEn
)

type Resumption added in v0.2.0 

type Resumption struct {
	RestorePath string
	Restorer    PersistenceRestorer
	Strategy    ResumeStrategyEnum
}

Resumption

type Runnable added in v0.2.0 

type Runnable interface {
	Run(args ...any) (*TraverseResult, error)
}

type RunnerInfo added in v0.2.1 

type RunnerInfo struct {
	ResumeInfo       *Resumption
	PrimeInfo        *Prime
	AccelerationInfo *Acceleration
}

type SampleTypeEnum added in v0.4.0 

type SampleTypeEnum uint

SampleTypeEnum determines the type of sampling to use 

const (
	SampleTypeUnsetEn SampleTypeEnum = iota
	SampleTypeSliceEn
	SampleTypeFilterEn
	SampleTypeCustomEn
)

type SamplerOptions added in v0.4.0 

type SamplerOptions struct {
	// Custom allows the client to customise how a directory's contents are sampled.
	// The default way to sample is either by slicing the directory's contents or
	// by using the filter to select either the first/last n entries (using the
	// SamplingOptions). If the client requires an alternative way of creating a
	// sample, eg to take all files greater than a certain size, then this
	// can be achieved by specifying Each and While inside Custom.
	Custom SamplingIteratorOptions
}

SamplerOptions

type SamplingIteratorOptions added in v0.4.0 

type SamplingIteratorOptions struct {
	// Each enables customisation of the sampling functionality, instead of using
	// the defined filter. A directory's contents is sampled according to this
	// function. The function receives the TraverseItem being considered and should
	// return true to include in the sample, false otherwise.
	Each EachDirectoryItemPredicate

	// While enables customisation of the sampling functionality, instead of using
	// the defined filter. The sampling loop will continue to run while this
	// condition is true. The predicate function should return false once condition
	// has been met to complete the sample. Of course, the loop will only run while
	// there are still remaining items to consider (ie there are no more entries
	// to consider for the current traverse item).
	While WhileDirectoryPredicate
}

type SamplingOptions added in v0.4.0 

type SamplingOptions struct {
	// SampleInReverse determines the direction of iteration for the sampling
	// operation
	SampleInReverse bool

	// SampleType the type of sampling to use
	SampleType SampleTypeEnum

	// NoOf specifies number of items required in each sample (only applies
	// when not using Custom iterator options)
	NoOf EntryQuantities
}

type Session added in v0.2.0 

type Session interface {
	StartedAt() time.Time
	Elapsed() time.Duration
}

type SessionRunner added in v0.2.0 

type SessionRunner interface {
	With(with CreateNewRunnerWith, info *RunnerInfo) NavigationRunner
	Primary(info *Prime) NavigationRunner
	Resume(info *Resumption) NavigationRunner
}

func New added in v0.2.0 

func New() SessionRunner

type SkipTraversal added in v0.4.0 

type SkipTraversal uint
const (
	SkipNoneTraversalEn SkipTraversal = iota
	SkipDirTraversalEn
	SkipAllTraversalEn
)

type SortBehaviour 

type SortBehaviour struct {
	// case sensitive traversal order
	//
	IsCaseSensitive bool

	// DirectoryEntryOrder defines whether a folder's files or directories
	// should be navigated first.
	//
	DirectoryEntryOrder DirectoryContentsOrderEnum
}

SortBehaviour

type SortEntriesHookFn 

type SortEntriesHookFn func(entries []fs.DirEntry, custom ...any) error

SortEntriesHookFn hook function to define how directory entries are sorted. Does not have to be set explicitly. This will be set according to the IsCaseSensitive on the TraverseOptions, but can be overridden if needed.

type SubPathBehaviour 

type SubPathBehaviour struct {
	KeepTrailingSep bool
}

SubPathBehaviour

type SubPathHookFn 

type SubPathHookFn func(info *SubPathInfo) string

SubPathHookFn

type SubPathInfo 

type SubPathInfo struct {
	Root      string
	Item      *TraverseItem
	Behaviour *SubPathBehaviour
}

SubPathInfo

type TraverseCallback 

type TraverseCallback func(item *TraverseItem) error

TraverseCallback defines traversal callback function signature.

type TraverseFilter 

type TraverseFilter interface {
	// Description describes filter
	Description() string

	// Validate ensures the filter definition is valid, panics when invalid
	Validate()

	// Source, filter definition (comes from filter definition Pattern)
	Source() string

	// IsMatch does this item match the filter
	IsMatch(item *TraverseItem) bool

	// IsApplicable is this filter applicable to this item's scope
	IsApplicable(item *TraverseItem) bool

	// Scope, what items this filter applies to
	Scope() FilterScopeBiEnum
}

TraverseFilter filter that can be applied to file system entries. When specified, the callback will only be invoked for file system nodes that pass the filter.

type TraverseHooks 

type TraverseHooks struct {
	QueryStatus   QueryStatusHookFn
	ReadDirectory ReadDirectoryHookFn
	FolderSubPath SubPathHookFn
	FileSubPath   SubPathHookFn
	InitFilters   FilterInitHookFn
	Sort          SortEntriesHookFn
	Extend        ExtendHookFn
}

TraverseHooks defines the suite of items that can be customised by the client

type TraverseItem 

type TraverseItem struct {
	Path      string
	Entry     fs.DirEntry  // contains a FileInfo via Info() function
	Info      fs.FileInfo  // optional file info instance
	Extension ExtendedItem // extended information about the file system node, if requested
	Error     error
	Children  []fs.DirEntry

	Parent *TraverseItem
	// contains filtered or unexported fields
}

TraverseItem info provided for each file system entity encountered during traversal. The root item does not have a DirEntry because it is not created as a result of a readDir invoke. Therefore, the client has to know that when its function is called back, they will be no DirEntry for the root entity.

func (*TraverseItem) IsDirectory added in v0.6.0 

func (ti *TraverseItem) IsDirectory() bool

type TraverseItemInput added in v0.2.0 

type TraverseItemInput struct {
	Item  *TraverseItem
	Label string
	Fn    TraverseCallback
}

type TraverseItemJob added in v0.2.0 

type TraverseItemJob = boost.Job[TraverseItemInput]

type TraverseItemJobStream added in v0.2.0 

type TraverseItemJobStream = boost.JobStream[TraverseItemInput]

type TraverseItemJobStreamR added in v0.2.0 

type TraverseItemJobStreamR = boost.JobStreamR[TraverseItemInput]

type TraverseItemJobStreamW added in v0.2.0 

type TraverseItemJobStreamW = boost.JobStreamW[TraverseItemInput]

type TraverseItemOutput added in v0.2.0 

type TraverseItemOutput = boost.JobOutput[TraverseOutput]

type TraverseItemOutputStream added in v0.2.0 

type TraverseItemOutputStream = boost.JobOutputStream[TraverseOutput]

type TraverseItemOutputStreamR added in v0.2.0 

type TraverseItemOutputStreamR = boost.JobOutputStreamR[TraverseOutput]

type TraverseItemOutputStreamW added in v0.2.0 

type TraverseItemOutputStreamW = boost.JobOutputStreamW[TraverseOutput]

type TraverseNavigator 

type TraverseNavigator interface {
	// contains filtered or unexported methods
}

TraverseNavigator interface to the main traverse instance.

type TraverseOptionFn 

type TraverseOptionFn func(o *TraverseOptions)

TraverseOptionFn functional traverse options

type TraverseOptions 

type TraverseOptions struct {
	Store OptionsStore

	// Callback function to invoke for every item visited in the file system.
	//
	Callback *LabelledTraverseCallback `json:"-"`

	// Notify collection of notification function.
	//
	Notify Notifications `json:"-"`

	// TraverseHooks collection of hook functions, that can be overridden.
	//
	Hooks TraverseHooks `json:"-"`

	// Persist contains options for persisting traverse options
	//
	Persist PersistOptions `json:"-"`

	// Sampler defines options for sampling directory entries. There are
	// multiple ways of performing sampling. The client can either:
	// A) Use one of the four predefined functions see (SamplerOptions.Fn)
	// B) Use a Custom iterator. When setting the Custom iterator properties
	//
	Sampler SamplerOptions `json:"-"`

	// Monitor contains externally provided logger
	//
	Monitor MonitorOptions `json:"-"`
}

TraverseOptions customise the way a directory tree is traversed

func GetDefaultOptions 

func GetDefaultOptions() *TraverseOptions

GetDefaultOptions

func (*TraverseOptions) Clone 

func (o *TraverseOptions) Clone() *TraverseOptions

type TraverseOutput added in v0.2.0 

type TraverseOutput struct {
	Item  *TraverseItem
	Error error
}

type TraverseResult 

type TraverseResult struct {
	Session Session
	Metrics *NavigationMetrics
	// contains filtered or unexported fields
}

TraverseResult the result of the traversal process.

type TraverseSession added in v0.1.17 

type TraverseSession interface {
	Session

	Save(path string) error
	// contains filtered or unexported methods
}

type TraverseSubscription 

type TraverseSubscription uint

TraverseSubscription type to define traversal subscription (for which file system items the client defined callback are invoked for). 

const (
	SubscribeAny              TraverseSubscription // invoke callback for files and folders
	SubscribeFolders                               // invoke callback for folders only
	SubscribeFoldersWithFiles                      // invoke callback for folders only but include files
	SubscribeFiles                                 // invoke callback for files only
)

type TriStateBoolEnum 

type TriStateBoolEnum uint
const (
	TriStateBoolUnsetEn TriStateBoolEnum = iota
	TriStateBoolTrueEn
	TriStateBoolFalseEn
)

type WhileDirectoryPredicate added in v0.4.0 

type WhileDirectoryPredicate func(fi *FilteredInfo) bool

WhileDirectoryPredicate determines when to terminate the loop

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.