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]

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.

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

Like searchByRankedSuffix, but also keeps the names around.

Like searchBySuffix, but also keeps the names around.

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

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.