ddt

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2020 License: BSD-3-Clause Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Basenames matching this pattern are considered configuration files.
	NodeMetaRegexp = regexp.MustCompile(`(?i)^(index|meta)\.(json|ya?ml)$`)

	// Basenames matching this pattern are considered documents.
	NodeDocsRegexp = regexp.MustCompile(`(?i)^.*\.(md|markdown|html?|txt)$`)

	// Files that are not considered to be assets in addition to node
	// meta and doc files.
	NodeAssetsIgnoreRegexp = regexp.MustCompile(`(?i)^(dsk|dsk\.(json|ya?ml)|AUTHORS\.txt|empty)$`)

	// Characters that are ignored when looking up an URL,
	// i.e. "foo/bar baz" and "foo/barbaz" are than equal.
	NodeLookupURLIgnoreChars = regexp.MustCompile(`[\s\-_]+`)

	// Patterns for extracting order number and title from a node's
	// path/URL segment in the form of 06_Foo. As well as for
	// "slugging" the URL/path segment.
	NodePathTitleRegexp        = regexp.MustCompile(`^0?(\d+)[_,-]+(.*)$`)
	NodePathInvalidCharsRegexp = regexp.MustCompile(`[^A-Za-z0-9-_]`)
	NodePathMultipleDashRegexp = regexp.MustCompile(`-+`)
)
View Source 
var (
	ErrTreeRootNotFound = errors.New("no tree root found")
)

Functions

func AlternateNames 

func AlternateNames(name string) []string

Types

type Node 

type Node struct {
	// Ensure node is locked for writes, when updating the node's hash
	// value cache.
	sync.RWMutex

	// Absolute path to the node's directory.
	Path string

	// The parent ddt. If this is the root node, left unset.
	Parent *Node

	// A list of children nodes.
	Children []*Node
	// contains filtered or unexported fields
}

Node represents a directory inside the design definitions tree.

func NewNode 

func NewNode(
	path string,
	root string,
	cdb config.DB,
	mdb meta.DB,
	adb author.DB,
) *Node

NewNode constructs a new Node using its path in the filesystem and initalizing fields. The initialization must finalized by using Load().

func (*Node) Asset 

func (n *Node) Asset(name string) (bool, *NodeAsset, error)

Asset returns the that matches name. Generally we don't support order numbers on assets, they make sense on documents and design aspects but do not make sense on assets.

However users may assume, they can be used on assets too.

Assuming 02_cat.jpg exists in the filesystem, both a request for 02_cat.jpg and a request for cat.jpg will succeed.

However there is one side-effect that is undesired but okay for us: having cat.jpg and requesting 02_cat.jpg or using any other order prefix will succeed. This behavior is not guaranteed to work in future versions.

func (*Node) Assets 

func (n *Node) Assets() ([]*NodeAsset, error)

Assets are all files inside the node directory excluding system files, node documents and meta files.

func (*Node) Authors 

func (n *Node) Authors() []*author.Author

Returns a list of node authors; wil use the given authors database to augment data with full name if possible.

func (*Node) CalculateHash 

func (n *Node) CalculateHash() (string, error)

CalculateHash calculates a good enough hash over all aspects of the node, including its children. Excludes parent in calculation, as it would cause an infinite loop.

Will cache the once calculated hash, and use the cached on if exists. The assumption here is that the node will be entirely re-initialized when it changes.

func (*Node) Create 

func (n *Node) Create() error

func (*Node) CreateDoc 

func (n *Node) CreateDoc(name string, contents []byte) error

CreateDoc creates a document in the node's directory.

func (*Node) CreateMeta 

func (n *Node) CreateMeta(name string, meta *NodeMeta) error

CreateMeta creates a meta file in the node's directory using the given name as the file name. The provided Meta struct, does not need to have its path initialized, this is done by this function.

func (*Node) Crumbs 

func (n *Node) Crumbs(get NodeGetter) []*Node

Returns a list of crumbs. The last element is the current active one. Does not include a root ddt.

func (*Node) Custom 

func (n *Node) Custom() interface{}

func (*Node) Description 

func (n *Node) Description() string

Returns the full description of the ddt.

func (*Node) Docs 

func (n *Node) Docs() ([]*NodeDoc, error)

Returns a slice of documents for this ddt.

The provided tree URL prefix will be used to resolve and make relative links inside the document absolute. This is usually something like: /api/v1/tree

func (*Node) Keywords 

func (n *Node) Keywords() []string

Returns a list of keywords terms. Deprecated, will be removed once APIv1 search support is removed.

func (*Node) Load 

func (n *Node) Load() error

Load node meta data from the first config file found and further initialize Node.

func (*Node) LookupURL 

func (n *Node) LookupURL() string

Returns the normalized and lower cased lookup URL for this ddt.

func (*Node) Modified 

func (n *Node) Modified() (time.Time, error)

Modified finds the most recent modified time of this node, including assets and docs.

func (*Node) Name 

func (n *Node) Name() string

Name is the basename of the file without its order number.

func (*Node) Order 

func (n *Node) Order() uint64

An order number, as a hint for outside sorting mechanisms.

func (*Node) Related 

func (n *Node) Related(get NodeGetter) []*Node

Returns a list of related nodes.

func (*Node) Tags 

func (n *Node) Tags() []string

Returns an alphabetically sorted list of tags.

func (*Node) Title 

func (n *Node) Title() string

The node's computed title with any ordering numbers stripped off, usually for display purposes. We normalize the title string to make sure all special characters are represented in their composed form. Some filesystems store filenames in decomposed form. Using these directly in the frontend led to visual inconsistencies. See: https://blog.golang.org/normalization

func (*Node) URL 

func (n *Node) URL() string

Returns the normalized URL path fragment, that can be used to address this node i.e Input/Password.

func (*Node) UnnormalizedURL 

func (n *Node) UnnormalizedURL() string

Returns the unnormalized URL path fragment.

func (*Node) Version 

func (n *Node) Version() string

type NodeAsset 

type NodeAsset struct {
	// Absolute path to the file.
	Path string

	// The URL, relative to the design defintion tree root.
	URL string
	// contains filtered or unexported fields
}

An emebeddable or otherwise downloadable file.

func NewNodeAsset 

func NewNodeAsset(path string, URL string, mdb meta.DB) *NodeAsset

func (NodeAsset) As 

func (a NodeAsset) As(targetExt string) (bool, io.ReadSeeker, error)

As returns the node assets' contents, converted to the type indicated by given extensions. The extensions should include the a leading ".".

func (NodeAsset) Dimensions 

func (a NodeAsset) Dimensions() (ok bool, w int, h int, err error)

Dimensions for asset media when these are possible to detect. "ok" indicates if the format was supported.

func (NodeAsset) Modified 

func (a NodeAsset) Modified() (time.Time, error)

func (NodeAsset) Name 

func (a NodeAsset) Name() string

Name is the basename of the file. The canonical name of the asset intentionally contains (non-functional) order numbers if the are used.

func (NodeAsset) Size 

func (a NodeAsset) Size() (int64, error)

Size returns the file size in bytes.

func (NodeAsset) Title 

func (a NodeAsset) Title() string

Title derived from the cleaned-up basename.

type NodeDoc 

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

NodeDoc is a document file.

func (NodeDoc) CleanText 

func (d NodeDoc) CleanText() ([]byte, error)

Text converted from original file format.

func (NodeDoc) Components 

func (d NodeDoc) Components() ([]*NodeDocComponent, error)

Components as found in the raw document.

func (NodeDoc) HTML 

func (d NodeDoc) HTML(treePrefix string, nodeURL string, nodeGet NodeGetter, nodeSource string) ([]byte, error)

HTML as parsed from the underlying file. The provided tree prefix and node URL will be used to resolve relative source and node URLs inside the documents, to i.e. make them absolute.

func (NodeDoc) Name 

func (d NodeDoc) Name() string

Name is the basename of the file without its order number.

func (NodeDoc) Order 

func (d NodeDoc) Order() uint64

Order is a hint for outside sorting mechanisms.

func (NodeDoc) Raw 

func (d NodeDoc) Raw() ([]byte, error)

Raw content of the underlying file.

func (NodeDoc) Title 

func (d NodeDoc) Title() string

Title of the document and computed with any ordering numbers and the extension stripped off, usually for display purposes. We normalize the title string to make sure all special characters are represented in their composed form. For more on this topic see the docblock of Node.Title().

type NodeDocComponent 

type NodeDocComponent struct {
	Id       int // Unique ID
	Raw      string
	Level    int // Nesting level
	Position int // Start position inside document.
	Length   int // Length of the component code.
}

func NewNodeDocComponent 

func NewNodeDocComponent(raw string, level int, position int) *NodeDocComponent

func (*NodeDocComponent) Placeholder 

func (c *NodeDocComponent) Placeholder() string

type NodeDocTransformer 

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

NodeDocTransformer post-processes given HTML after it has been processed file-type specific parsers. See NodeDoc.HTML().

Makes the HTML more portable, by turning relative source links into absolute ones. We need to have all source URLs absolute as documents can be placed anywhere inside the frontend's URL structure.

All references to nodes and node assets are discovered and re-constructed as an absolute URL, using the canonical node URL.

All other relative links are made absolute using treeBase.

For elements referencing a node, "data-node" attribute containing the node's ref-URL is added. For elements referencing a node asset, a "data-node" attribute containing the node's ref-URL is added and a "data-node-asset" attribute with the name of the asset is added.

Dimension attributes are added to images of nodes.

HTML inside <code> tags is escaped while preventing double escaping.

func NewNodeDocTransformer 

func NewNodeDocTransformer(treePrefix string, nodeURL string, nodeGet NodeGetter, nodeSource string) (*NodeDocTransformer, error)

NewNodeDocTransformer returns an initialized NodeDocTransformer, it'll derive values for nodeBase and treeBase from the treePrefix and nodeURL.

func (NodeDocTransformer) ProcessHTML 

func (dt NodeDocTransformer) ProcessHTML(contents []byte) ([]byte, error)

ProcessHTML is the main entry point.

type NodeGetter 

type NodeGetter func(url string) (ok bool, n *Node, err error)

NodeGetter retrieves nodes from the tree, using the node's relative URL. When the node cannot be found ok will be false.

type NodeMeta 

type NodeMeta struct {

	// Email addresses of node authors.
	Authors     []string    `json:"authors,omitempty" yaml:"authors,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Related     []string    `json:"related,omitempty" yaml:"related,omitempty"`
	Tags        []string    `json:"tags,omitempty" yaml:"tags,omitempty"`
	Custom      interface{} `json:"custom,omitempty" yaml:"custom,omitempty"`

	// Freeform version string.
	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	// Deprecated, will be removed once APIv1 search support is removed.
	Keywords []string `json:"keywords,omitempty" yaml:"keywords,omitempty"`
	// contains filtered or unexported fields
}

Metadata parsed from node configuration.

func (*NodeMeta) Create 

func (m *NodeMeta) Create() error

func (*NodeMeta) Load 

func (m *NodeMeta) Load() error

type NodesGetter 

type NodesGetter func() []*Node

NodesGetter retrieves all nodes from the tree.

type Tree 

type Tree struct {
	// Ensures the tree is locked, when it is being synced, to
	// prevent reads in the middle of syncs.
	sync.RWMutex

	// The absolute root path of the tree.
	Path string

	// The root node and entry point to the acutal tree.
	Root *Node `json:"root"`
	// contains filtered or unexported fields
}

func NewTree 

func NewTree(
	path string,
	cdb config.DB,
	adb author.DB,
	mdb meta.DB,
	b *bus.Broker,
) (*Tree, error)

NewTree construct and initializes a Tree.

func (*Tree) CalculateHash 

func (t *Tree) CalculateHash() (string, error)

func (*Tree) Get 

func (t *Tree) Get(url string) (ok bool, n *Node, err error)

Retrieves a node from the tree, performs a case-insensitive match.

func (*Tree) GetAll 

func (t *Tree) GetAll() []*Node

GetAll nodes as a flat slice.

func (*Tree) NeighborNodes 

func (t *Tree) NeighborNodes(current *Node) (prev *Node, next *Node, err error)

Returns the neighboring previous and next nodes for the given current ddt. When current node is the last or first node, the behavior is not to wrap around.

Determines the next node following the given current ddt. This may either be the first child of the given node, if there are none the sibling node and - walking up the tree - if there is none the parents sibling ddt. The algorithm for determing the previous node is analogous.

func (*Tree) String 

func (t *Tree) String() string

func (*Tree) Sync 

func (t *Tree) Sync() error

Sync recursively crawls the given root directory, constructing a tree of nodes. Will rebuild the entire tree on every sync. This makes the algorithm really simple - as we don't need to do branch selection - but also slow.

Nodes that are discover but fail to finalize their initialization using Node.Load() will not be skipped but kept in tree in a semi-initialized way. So that the their children are not disconnected and no gaps exist in tree branches.

It will not descend into directories it considers hidden (their name is prefixed by a dot), except when the given directory itself is dot-hidden.

func (*Tree) TotalNodes 

func (t *Tree) TotalNodes() uint16

Returns the number of total nodes in the tree.

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.