A name is an absolute-or-relative non-empty list of name segments. It is used to represent the path to a definition.

A few example names:

• "foo.bar" --> Name Relative ("bar" :| ["foo"])
• ".foo.bar" --> Name Absolute ("bar" :| ["foo"])
• "|>.-- Name Relative (":| ["|"])
• "." --> Name Relative ("." :| [])
• ".." --> Name Absolute (".." :| [])

Cons a name segment onto the head of a relative name. Not monotonic with respect to ordering! It is not safe to use cons s as the first argument to Map.mapKeysMonotonic!

Precondition: the name is relative

O(n), where n is the number of segments.

Snoc a name segment onto the end of a name.

O(1).

Construct a relative name from a name segment.

O(1).

Construct a relative name from a list of name segments.

>>> fromSegments ("a" :| ["b", "c"])
"a.b.c"

O(n), where n is the number of name segments.

Construct a relative name from a list of name segments which are in reverse order

>>> fromReverseSegments ("c" :| ["b", "a"])
a.b.c

O(1)

Return the number of name segments in a name.

O(n), where n is the number of name segments.

Is this name absolute?

O(1).

Is this name relative?

O(1).

isPrefixOf x y returns whether x is a prefix of (or equivalent to) y, which is false if one name is relative and the other is absolute.

>>> isPrefixOf "a.b" "a.b.c"
True

>>> isPrefixOf "a.b.c" "a.b.c"
True

>>> isPrefixOf ".a.b" "a.b.c"
False

O(n), where n is the number of name segments.

beginsWithSegment name segment returns whether name's first name segment is segment.

>>> beginsWithSegment "abc.def" "abc"
True

>>> beginsWithSegment "abc.def" "ab"
False

O(n), where n is the number of name segments.

Like endsWithSegments, but accepts a list of name segments in reverse order.

Slightly more efficient than endsWithSegments.

>>> endsWithReverseSegments "a.b.c" ["c", "b"]
True

endsWithSegments x y returns whether x ends with y.

>>> endsWithSegments "a.b.c" ["b", "c"]
True

>>> endsWithSegments "a.b.c" ["d"]
False

>>> endsWithSegments "a.b.c" []
True

O(n), where n is the number of name segments.

Like stripReversedPrefix but if the prefix doesn't match, or if it would strip the entire name away just return the original name.

>>> tryStripReversedPrefix (fromReverseSegments ("c" :| ["b", "a"])) ["b", "a"]
Name Relative (NameSegment {toText = "c"} :| [])
>>> tryStripReversedPrefix (fromReverseSegments ("y" :| ["x"])) ["b", "a"]
Name Relative (NameSegment {toText = "y"} :| [NameSegment {toText = "x"}])

>>> tryStripReversedPrefix (fromReverseSegments ("c" :| ["b", "a"])) ["b", "a"]
Name Relative (NameSegment {toText = "c"} :| [])

Return the name segments of a name, in reverse order.

>>> reverseSegments "a.b.c"
"c" :| ["b", "a"]

O(1).

Return the name segments of a name.

>>> segments "a.b.c"
"a" :| ["b", "c"]

O(n), where n is the number of name segments.

Return all relative suffixes of a name, in ascending-length order. The returned list will always be non-empty.

>>> suffixes "a.b.c"
["a.b.c", "a.b", "c"]

>>> suffixes ".a.b.c"
["a.b.c", "a.b", "c"]

Return the final segment of a name.

>>> lastSegment (fromSegments ("base" :| ["List", "map"]))
NameSegment {toText = "map"}

Make a name absolute. No-op if the name is already absolute.

O(1).

Make a name relative. No-op if the name is already relative.

O(1).

Overwrite a name's position. This only changes the name's tag, it performs no manipulations to the segments of the name.

O(1).

Compute the "parent" of a name, unless the name is only a single segment, in which case it has no parent.

>>> parent "a.b.c"
Just "a.b"

>>> parent ".a.b.c"
Just ".a.b"

>>> parent "a"
Nothing

stripNamePrefix x y strips prefix x from name y, and returns the resulting name. Returns Nothing x is not a proper (meaning shorter-than) prefix of y.

>>> stripNamePrefix "a.b" "a.b.c"
Just "c"

>>> stripNamePrefix ".a.b" "a.b.c"
Nothing

>>> stripNamePrefix "a.b.c" "a.b.c"
Nothing

Drop all leading segments from a name, retaining only the last segment as a relative name.

>>> unqualified "a.b.c"
"c"

>>> unqualified ".a.b.c"
"c"

Returns the common prefix of two names as segments

Note: the returned segments are NOT reversed.

>>> commonPrefix "a.b.x" "a.b.y"
[a,b]

>>> commonPrefix "x.y.z" "a.b.c"
[]

>>> commonPrefix "a.b.c" "a.b.c.d.e"
[a,b,c]

Must have equivalent positions or no there's no common prefix >>> commonPrefix ".a.b.c" "a.b.c.d.e" []

Prefix matches are performed at the *segment* level: >>> commonPrefix "a.bears" "a.beats" [a]

precondition: input list is deduped, and so is the Name list in the tuple

Like searchBySuffix, but also keeps the names around.

Like searchByRankedSuffix, but also keeps the names around.

Return all "splits" of a relative name, which pair a possibly-empty prefix of name segments with a suffix, such that the original name is equivalent to prefix + suffix.

Note: always returns a non-empty list, but (currently) does not use NonEmpty for convenience, as none of the call-sites care if the list is empty or not.

> splits foo.bar.baz

  prefix    suffix
  ------    ------
  ∅         foo.bar.baz
  foo       bar.baz
  foo.bar   baz

Precondition: the name is relative.

compareSuffix x y compares the suffix of y (in reverse segment order) that is as long as x to x (in reverse segment order).

>>> compareSuffix "b.c" "a.b.c"
EQ -- because [c,b] == [c,b]

>>> compareSuffix "b.c" "a.b.b"
LT -- because [b,b] < [c,b]

>>> compareSuffix "a.b.c" "b.c"
LT -- because [c,b] < [c,b,a]

>>> compareSuffix "b.b" "a.b.c"
GT -- because [c,b] > [b,b]

Used for suffix-based lookup of a name. For instance, given a r : Relation Name x, Relation.searchDom (compareSuffix "foo.bar") r will find all r whose name has foo.bar as a suffix.

This is only exported for testing; use searchBySuffix or shortestUniqueSuffix instead.

O(n), where n is the number of name segments.