nav

package
v0.1.15 Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2023 License: MIT Imports: 15 Imported by: 5

Documentation

Index

Constants

View Source 
const (
	JSONMarshallNoPrefix      = ""
	JSONMarshall2SpacesIndent = "  "
)

Variables

This section is empty.

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 DefaultExtendHookFn 

func DefaultExtendHookFn(navi *NavigationInfo, entries *DirectoryEntries)

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 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 QuerySkipDirError 

func QuerySkipDirError(target error) bool

QuerySkipDirError query if error is the fs SkipDir error

func ReadEntries 

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

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

func RootItemSubPath 

func RootItemSubPath(info *SubPathInfo) string

RootItemSubPath

func RootParentSubPath 

func RootParentSubPath(info *SubPathInfo) string

RootParentSubPath

func Tail 

func Tail(input string, offset int) string

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

Types

type ActiveState 

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

type AscendancyHandler 

type AscendancyHandler func(_ *TraverseItem)

AscendancyHandler defines the signatures of ascend/descend handlers

type BeginHandler 

type BeginHandler func(_ *NavigationState)

BeginHandler life cycle event handler, invoked before start of traversal

type ClientLogger 

type ClientLogger interface {
	Debug(_ string, _ ...log.Field)
	Info(_ string, _ ...log.Field)
	Warn(_ string, _ ...log.Field)
	Error(_ string, _ ...log.Field)
}

ClientLogger

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 DirectoryEntries 

type DirectoryEntries struct {
	Options *TraverseOptions
	Order   DirectoryEntryOrderEnum
	Folders []fs.DirEntry
	Files   []fs.DirEntry
}

DirectoryEntries

type DirectoryEntryOrderEnum 

type DirectoryEntryOrderEnum uint

DirectoryEntryOrderEnum determines what order a directories entries are invoked for. 

const (
	// DirectoryEntryOrderFoldersFirstEn invoke folders first
	DirectoryEntryOrderFoldersFirstEn DirectoryEntryOrderEnum = iota

	// DirectoryEntryOrderFilesFirstEn invoke files first
	DirectoryEntryOrderFilesFirstEn
)

type EndHandler 

type EndHandler func(_ *TraverseResult)

EndHandler life cycle event handler, invoked at end of traversal

type ExtendHookFn 

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

ExtendHookFn

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:"-"`
}

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

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

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

func (FilterScopeBiEnum) String 

func (f FilterScopeBiEnum) String() string

String converts enum value to a string

type FilterTypeEnum 

type FilterTypeEnum uint
const (
	FilterTypeUndefinedEn FilterTypeEnum = iota

	// FilterTypeRegexEn regex filter
	FilterTypeRegexEn

	// FilterTypeGlobEn glob filter
	FilterTypeGlobEn

	// FilterTypeCustomEn client definable filter
	FilterTypeCustomEn
)

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 LoggingOptions 

type LoggingOptions struct {

	// Enabled controls logging actuation
	Enabled bool

	// Path of log file
	Path string

	// TimeStampFormat format of the timestamp field in generated logs
	TimeStampFormat string

	// Level controls which the level of logging desired
	Level log.Level

	// Rotation log file rotation options
	Rotation LogRotationOptions
}

LoggingOptions

type Metric 

type Metric struct {
	Name  string
	Count uint
}

Metric

type MetricCollection 

type MetricCollection map[MetricEnum]*Metric

MetricCollection

type MetricEnum 

type MetricEnum uint
const (
	// No of files invoked for during traversal
	//
	MetricNoFilesEn MetricEnum = iota

	// No of folders invoked for during traversal
	//
	MetricNoFoldersEn
)
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
}

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
	Frame   *navigationFrame
}

NavigationInfo 

type NavigationRunner interface {
	Run() (*TraverseResult, error)
}
type NavigationState struct {
	Root    *utils.VarProp[string]
	Filters *NavigationFilters
	Logger  utils.RoProp[ClientLogger]
}

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 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

	// DoExtend request an extended result.
	//
	DoExtend bool

	// 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

	// Logging options
	//
	Logging LoggingOptions
}

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 PrimarySession 

type PrimarySession struct {
	Path string
	// contains filtered or unexported fields
}

func (*PrimarySession) Configure 

func (s *PrimarySession) Configure(fn ...TraverseOptionFn) NavigationRunner

Configure is the pre run stage for a primary session

func (*PrimarySession) Save 

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

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

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 ResumeSession 

type ResumeSession struct {
	Path     string
	Strategy ResumeStrategyEnum
	// contains filtered or unexported fields
}

func (*ResumeSession) Configure 

func (s *ResumeSession) Configure(restore func(o *TraverseOptions, active *ActiveState)) NavigationRunner

Configure is the pre run stage for a resume session

func (*ResumeSession) Save 

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

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

type ResumeStrategyEnum 

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

type ResumerInfo 

type ResumerInfo struct {
	RestorePath string
	Restorer    PersistenceRestorer
	Strategy    ResumeStrategyEnum
}

ResumerInfo

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 DirectoryEntryOrderEnum
}

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
	// 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) IsDir 

func (ti *TraverseItem) IsDir() bool

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:"-"`
}

TraverseOptions customise the way a directory tree is traversed

func GetDefaultOptions 

func GetDefaultOptions() *TraverseOptions

GetDefaultOptions

func (*TraverseOptions) Clone 

func (o *TraverseOptions) Clone() *TraverseOptions

type TraverseResult 

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

TraverseResult the result of the traversal process.

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
)

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.