platform-bible-utils
    Preparing search index...

    Type Alias UsjDocumentLocation

    A JSONPath query to a MarkerContent, Usj, or property within a USJ document and additional information that point to a specific location in that USJ document.

    This type does not include a verse reference because the JSONPath is relative to a specific USJ document; that USJ document may have a book, a chapter, or something else in it. Use UsjLocation to specify which USJ document this location is relative to, making the location an absolute verse reference location. The closest equivalent concept in USFM to this relative document location is a string character index in a USFM document; such an index is relative to a specific USFM document rather than indicating an absolute position in a Scripture text.

    This type intends to represent USFM positions (UsfmVerseLocation) in USJ space. However, there are some USFM positions that are not currently representable with these types:

    • The second slash in optbreak's USFM representation // (literally not representable)
    • Nested marker prefix on opening markers like + for character markers (literally not representable)
    • The bar | that indicates the start of closing marker attributes (no official representation)
    • The equals sign for closing marker attributes (no official representation)
    • The quotes around closing marker attribute values (no official representation)
    • The space between closing marker attributes (no official representation)

    Also note that the following types do not specify a concrete location that is actually in the USJ document but represent a USFM location relative to the most similar thing in USJ that there is:

    • UsjClosingMarkerLocation - there are no distinct closing objects in JSON; there is a common syntax for closing every object, but it is only one character and is on every single object as opposed to USFM closing markers which are multiple characters long and are only sometimes present.
    • UsjAttributeKeyLocation - when the attribute whose key is being pointed to is an attribute marker in USFM, the keyOffset does not apply to the USJ attribute name (e.g. altnumber) but to the USFM attribute marker name (e.g. ca).
    • UsjAttributeMarkerLocation - attribute markers are just properties in JSON; they do not have their own object such that they would have an opening that can be pointed to in the JSON like they have their own opening in USFM.
    • UsjClosingAttributeMarkerLocation - attribute markers are just properties in JSON, plus they are in the same situation as UsjClosingMarkerLocation as detailed above.

    Every USFM position has exactly one canonical location, which is the one UsjReaderWriter produces. One alias is allowed: a position at the end of a text string that is immediately followed by a marker or a closing marker may also be spelled as that string's offset at its length (the Scripture editor reports a caret held at the end of the text this way). Because of that alias, compare two locations by converting them with usjDocumentLocationToUsfmVerseRefVerseLocation, never by their shape. Following are clarifications on some tricky positions. In each example, the USFM is the whole document and | marks the position.

    • A position immediately in front of a marker. It is that marker's UsjMarkerLocation, at its backslash, even where it also follows the end of other content.

      \p In the beginning\f + \ft a note\f*|\v 2 God said
      

      { jsonPath: "$.content[0].content[2]" }

    • A position between two top-level blocks rather than inside either one. It is the start of the next block, the same as any position in front of a marker.

      \p God said
      |\b
      

      { jsonPath: "$.content[1]" }

    • The end of a character marker's or note's content. It is in front of the closing marker, so it is the closing marker's closingMarkerOffset 0. The text's offset at its length is the allowed alias.

      \p \nd LORD|\nd* said
      

      { jsonPath: "$.content[0].content[0]", closingMarkerOffset: 0 }

    • The end of a line. The newline that ends a line has no location of its own, so it is expressed on the line's last token as an offset at that token's length: a text offset at the string's length, or a closingMarkerOffset at the closing marker's length.

      \p In the beginning|
      \p God said
      

      { jsonPath: "$.content[0].content[0]", offset: 16 }

      \p In the beginning\f + \ft a note\f*|
      \p God said
      

      { jsonPath: "$.content[0].content[1]", closingMarkerOffset: 3 }

      A line that ends in a verse or chapter number ends on the number's propertyOffset at the number's length.

      \p
      \v 1|
      \p God said
      

      { jsonPath: "$.content[0].content[0]['number']", propertyOffset: 1 }

      An optbreak (//) has no closing marker and no location inside it, so every position from its start to the end of its line is the optbreak's own marker location.

      \p God said //|
      \p and it was so
      

      { jsonPath: "$.content[0].content[1]" }

    • Inside a paragraph that has no content. The only thing after its marker name is the newline, so the position is the marker name's propertyOffset at the name's length.

      \b|
      \p God said
      

      { jsonPath: "$.content[0]['marker']", propertyOffset: 1 }

    • The end of the document. It is one past the document's final newline, so it is the end of the last line (above) plus one.

      \p God said
      \b
      |
      

      { jsonPath: "$.content[1]['marker']", propertyOffset: 2 }

      \p God said
      |
      

      { jsonPath: "$.content[0].content[0]", offset: 9 }

    To see many examples of the same point represented by both USFM and USJ locations, go to https://github.com/paranext/paranext-core/tree/main/lib/platform-bible-utils/src/scripture/usj-reader-writer-test-data/testUSFM-2SA-1-locations.ts