@eagleoutice/flowr 2.9.2 → 2.9.3

package/util/range.d.ts

@@ -1,8 +1,10 @@
+import type { RNode } from '../r-bridge/lang-4.x/ast/model/model';
 /**
  * A source position in a file.
  *
  * Please note that some packages like `xmlparsedata` use their own start and end only to break ties
  * (e.g., `xmlparsedata` calculates them on a max col width approximation)
+ * @see {@link SourceRange|source ranges} for describing ranges of source positions.
  */
 export type SourcePosition = [
     /** starts with 1 */
@@ -11,15 +13,28 @@ export type SourcePosition = [
     column: number
 ];
 /**
+ * Utility functions for {@link SourcePosition|source positions}.
+ */
+export declare const SourcePosition: {
+    /**
+     * Formats a {@link SourcePosition|source position} as a human-readable string.
+     */
+    readonly format: (this: void, pos: SourcePosition | undefined) => string;
+    /**
+     * Creates a source position from the given line and column numbers.
+     * @param line - line number (starts with 1)
+     * @param column - column number (starts with 1)
+     */
+    readonly from: (this: void, line: number | string, column: number | string) => SourcePosition;
+    /**
+     * returns an invalid source position
+     */
+    readonly invalid: (this: void) => SourcePosition;
+};
+/**
+ * **Please note** that for multi-file projects we also have a {@link SourceLocation|source location} type that includes the file name.
  * Describe the start and end {@link SourcePosition|source position} of an element.
- * @see {@link rangeFrom} - to create a range
- * @see {@link mergeRanges} - to merge multiple ranges
- * @see {@link getRangeStart} - to get the start of a range
- * @see {@link getRangeEnd} - to get the end of a range
- * @see {@link rangeStartsCompletelyBefore} - to check if one range starts before another
- * @see {@link rangesOverlap} - to check if two ranges overlap
- * @see {@link addRanges} - to add two ranges
- * @see {@link rangeCompare} - to compare two ranges
+ * @see {@link SourceRange.format} and related utility functions for working with source ranges.
  */
 export type SourceRange = [
     /** inclusive start position */
@@ -29,55 +44,123 @@ export type SourceRange = [
     endLine: number,
     endColumn: number
 ];
-export declare function getRangeStart(p: undefined): undefined;
-export declare function getRangeStart(p: SourceRange): SourcePosition;
-export declare function getRangeStart(p: SourceRange | undefined): SourcePosition | undefined;
-export declare function getRangeEnd(p: undefined): undefined;
-export declare function getRangeEnd(p: SourceRange): SourcePosition;
-export declare function getRangeEnd(p: SourceRange | undefined): SourcePosition | undefined;
-/**
- * This does not ensure ordering of start and end!
- * @param sl - start line
- * @param sc - start column
- * @param el - end line
- * @param ec - end column
- */
-export declare function rangeFrom(sl: number | string, sc: number | string, el: number | string, ec: number | string): SourceRange;
-/**
- * @returns an invalid source range
- */
-export declare function invalidRange(): SourceRange;
-/**
- * Merges multiple source ranges into a single source range that spans from the earliest start to the latest end.
- * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
- * @throws if no ranges are provided
- */
-export declare function mergeRanges(rs?: (SourceRange | undefined)[]): SourceRange;
 /**
- * @returns true iff `r1` starts and ends before `r2` starts (i.e., if `r1` and `r2` do not overlap and `r1` comes before `r2`
+ * Utility functions for {@link SourceRange|source ranges}.
  */
-export declare function rangeStartsCompletelyBefore([, , r1el, r1ec]: SourceRange, [r2sl, r2sc, ,]: SourceRange): boolean;
+export declare const SourceRange: {
+    /**
+     * Prints a {@link SourceRange|range} as a human-readable string.
+     */
+    readonly format: (this: void, range: SourceRange | undefined) => string;
+    /**
+     * Returns the start position of a source range.
+     */
+    readonly getStart: (this: void, range: SourceRange) => SourcePosition;
+    /**
+     * Returns the start line of a source range.
+     */
+    readonly getStartLine: (this: void, range: SourceRange) => number;
+    /**
+     * Returns the end position of a source range.
+     */
+    readonly getEnd: (this: void, range: SourceRange) => SourcePosition;
+    /**
+     * Returns the end line of a source range.
+     */
+    readonly getEndLine: (this: void, range: SourceRange) => number;
+    /**
+     * Creates a source range from the given line and column numbers.
+     * @param sl - start line
+     * @param sc - start column
+     * @param el - end line
+     * @param ec - end column
+     */
+    readonly from: (this: void, sl: number | string, sc: number | string, el?: number | string, ec?: number | string) => SourceRange;
+    /**
+     * returns an invalid source range
+     */
+    readonly invalid: (this: void) => SourceRange;
+    /**
+     * Merges multiple source ranges into a single source range that spans from the earliest start to the latest end.
+     * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
+     * @throws if no ranges are provided
+     */
+    readonly merge: (this: void, rs: (SourceRange | undefined)[]) => SourceRange;
+    /**
+     * @returns true iff `r1` starts and ends before `r2` starts (i.e., if `r1` and `r2` do not overlap and `r1` comes before `r2`
+     */
+    readonly startsCompletelyBefore: (this: void, [, , r1el, r1ec]: SourceRange, [r2sl, r2sc, ,]: SourceRange) => boolean;
+    /**
+     * Checks if the two ranges overlap.
+     */
+    readonly overlap: (this: void, [r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange) => boolean;
+    /**
+     * Calculates the component-wise sum of two ranges.
+     */
+    readonly add: (this: void, [r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange) => SourceRange;
+    /**
+     * Provides a comparator for {@link SourceRange}s that sorts them in ascending order.
+     * @returns a positive number if `r1` comes after `r2`, a negative number if `r1` comes before `r2`, and `0` if they are equal
+     */
+    readonly compare: (this: void, [r1sl, r1sc, ,]: SourceRange, [r2sl, r2sc, ,]: SourceRange) => number;
+    /**
+     * Checks if the first range is a subset of the second range.
+     */
+    readonly isSubsetOf: (this: void, [r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange) => boolean;
+    /**
+     * Combines overlapping or subset ranges into a minimal set of ranges.
+     * @see {@link SourceRange.merge} for merging multiple ranges into a single range.
+     */
+    readonly combineRanges: (this: void, ...ranges: SourceRange[]) => SourceRange[];
+    readonly fromNode: <OtherInfo>(this: void, node: RNode<OtherInfo> | undefined) => SourceRange | undefined;
+};
 /**
- * Checks if the two ranges overlap.
+ * A source location consisting of a source range and an optional file name.
+ * @see {@link SourceLocation.format} and related utility functions for working with source locations.
  */
-export declare function rangesOverlap([r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange): boolean;
-/**
- * Calculate the component-wise sum of two ranges
- */
-export declare function addRanges([r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange): SourceRange;
-/**
- * Provides a comparator for {@link SourceRange}s that sorts them in ascending order.
- * @returns a positive number if `r1` comes after `r2`, a negative number if `r1` comes before `r2`, and `0` if they are equal
- */
-export declare function rangeCompare([r1sl, r1sc, ,]: SourceRange, [r2sl, r2sc, ,]: SourceRange): number;
-/**
- * Checks if the first range is a subset of the second range.
- */
-export declare function rangeIsSubsetOf([r1sl, r1sc, r1el, r1ec]: SourceRange, [r2sl, r2sc, r2el, r2ec]: SourceRange): boolean;
+export type SourceLocation = [...r: SourceRange, f?: string];
 /**
- * Combines overlapping or subset ranges into a minimal set of ranges.
- * If you are interested in merging overlapping ranges, see {@link mergeRanges}.
+ * Utility functions for {@link SourceLocation|source locations}.
  */
-export declare function combineRanges(...ranges: SourceRange[]): SourceRange[];
-/** A source location consisting of a source range and an optional file name. */
-export type SourceLocation = [...r: SourceRange, f?: string];
+export declare const SourceLocation: {
+    /**
+     * Formats a {@link SourceLocation|source location} as a human-readable string.
+     */
+    readonly format: (this: void, location: SourceLocation | undefined) => string;
+    /**
+     * Returns the {@link SourceRange|source range} part of a {@link SourceLocation|source location}.
+     */
+    readonly getRange: (this: void, location: SourceLocation) => SourceRange;
+    readonly getFile: (this: void, location: SourceLocation) => string | undefined;
+    /**
+     * Returns the file part of a {@link SourceLocation|source location}, or `undefined` if no file is set.
+     */
+    readonly from: (this: void, range: SourceRange, file?: string) => SourceLocation;
+    /**
+     * Creates a {@link SourceLocation|source location} from a {@link SourceRange|source range} and a file name.
+     * @returns undefined if the given range is undefined
+     * @see {@link SourceRange.fromNode} for getting the range from an AST node
+     */
+    readonly fromNode: <OtherInfo>(this: void, node: RNode<OtherInfo>) => SourceLocation | undefined;
+    /**
+     * Maps the file part of a {@link SourceLocation|source location} using the given mapper function.
+     */
+    readonly mapFile: (this: void, loc: SourceLocation, fileMapper: (file: string | undefined) => string) => SourceLocation;
+    /**
+     * Checks if the first location is a subset of the second location.
+     * For this, they must be in the same file!
+     * @see {@link SourceRange.isSubsetOf}
+     */
+    readonly isSubsetOf: (this: void, loc1: SourceLocation, loc2: SourceLocation) => boolean;
+    readonly compare: (this: void, loc1: SourceLocation, loc2: SourceLocation) => number;
+    /**
+     * Returns an invalid source location (i.e., with an invalid range and no file).
+     */
+    readonly invalid: (this: void) => SourceLocation;
+    /**
+     * Merges multiple source locations into a single source location that spans from the earliest start to the latest end.
+     * If the locations are from different files, `undefined` is returned.
+     * Files may be `undefined` themselves, but if there is at least one defined file, they must all be the same defined file for the merge to succeed.
+     */
+    readonly merge: (this: void, locs: (SourceLocation | undefined)[]) => SourceLocation | undefined;
+};

package/util/range.js

@@ -1,99 +1,260 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRangeStart = getRangeStart;
-exports.getRangeEnd = getRangeEnd;
-exports.rangeFrom = rangeFrom;
-exports.invalidRange = invalidRange;
-exports.mergeRanges = mergeRanges;
-exports.rangeStartsCompletelyBefore = rangeStartsCompletelyBefore;
-exports.rangesOverlap = rangesOverlap;
-exports.addRanges = addRanges;
-exports.rangeCompare = rangeCompare;
-exports.rangeIsSubsetOf = rangeIsSubsetOf;
-exports.combineRanges = combineRanges;
+exports.SourceLocation = exports.SourceRange = exports.SourcePosition = void 0;
 const assert_1 = require("./assert");
 /**
- * Returns the start position of a source range.
+ * Utility functions for {@link SourcePosition|source positions}.
  */
-function getRangeStart(p) {
-    return p === undefined ? undefined : [p[0], p[1]];
-}
-/**
- * Returns the end position of a source range.
- */
-function getRangeEnd(p) {
-    return p === undefined ? undefined : [p[2], p[3]];
-}
-/**
- * This does not ensure ordering of start and end!
- * @param sl - start line
- * @param sc - start column
- * @param el - end line
- * @param ec - end column
- */
-function rangeFrom(sl, sc, el, ec) {
-    return [Number(sl), Number(sc), Number(el), Number(ec)];
-}
-/**
- * @returns an invalid source range
- */
-function invalidRange() {
-    return [-1, -1, -1, -1];
-}
-/**
- * Merges multiple source ranges into a single source range that spans from the earliest start to the latest end.
- * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
- * @throws if no ranges are provided
- */
-function mergeRanges(rs = []) {
-    const rsSafe = rs.filter(assert_1.isNotUndefined);
-    (0, assert_1.guard)(rsSafe.length > 0, 'Cannot merge no ranges');
-    return rsSafe.reduce(([sl, sc, el, ec], [nsl, nsc, nel, nec]) => [
-        ...(sl < nsl || (sl === nsl && sc < nsc) ? [sl, sc] : [nsl, nsc]),
-        ...(el > nel || (el === nel && ec > nec) ? [el, ec] : [nel, nec])
-    ], rsSafe[0]);
-}
-/**
- * @returns true iff `r1` starts and ends before `r2` starts (i.e., if `r1` and `r2` do not overlap and `r1` comes before `r2`
- */
-function rangeStartsCompletelyBefore([, , r1el, r1ec], [r2sl, r2sc, ,]) {
-    return r1el < r2sl || (r1el === r2sl && r1ec < r2sc);
-}
-/**
- * Checks if the two ranges overlap.
- */
-function rangesOverlap([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
-    return r1sl <= r2el && r2sl <= r1el && r1sc <= r2ec && r2sc <= r1ec;
-}
-/**
- * Calculate the component-wise sum of two ranges
- */
-function addRanges([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
-    return [r1sl + r2sl, r1sc + r2sc, r1el + r2el, r1ec + r2ec];
-}
-/**
- * Provides a comparator for {@link SourceRange}s that sorts them in ascending order.
- * @returns a positive number if `r1` comes after `r2`, a negative number if `r1` comes before `r2`, and `0` if they are equal
- */
-function rangeCompare([r1sl, r1sc, ,], [r2sl, r2sc, ,]) {
-    if (r1sl === r2sl) {
-        return r1sc - r2sc;
-    }
-    else {
-        return r1sl - r2sl;
+exports.SourcePosition = {
+    /**
+     * Formats a {@link SourcePosition|source position} as a human-readable string.
+     */
+    format(pos) {
+        if (pos === undefined) {
+            return '??.??';
+        }
+        else {
+            return `${pos[0]}.${pos[1]}`;
+        }
+    },
+    /**
+     * Creates a source position from the given line and column numbers.
+     * @param line - line number (starts with 1)
+     * @param column - column number (starts with 1)
+     */
+    from(line, column) {
+        return [Number(line), Number(column)];
+    },
+    /**
+     * returns an invalid source position
+     */
+    invalid() {
+        return [-1, -1];
     }
-}
+};
 /**
- * Checks if the first range is a subset of the second range.
+ * Utility functions for {@link SourceRange|source ranges}.
  */
-function rangeIsSubsetOf([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
-    return (r1sl > r2sl || r1sl === r2sl && r1sc >= r2sc) && (r1el < r2el || r1sl === r2sl && r1ec <= r2ec);
-}
+exports.SourceRange = {
+    /**
+     * Prints a {@link SourceRange|range} as a human-readable string.
+     */
+    format(range) {
+        if (range === undefined) {
+            return '??-??';
+        }
+        else if (range[0] === range[2]) {
+            if (range[1] === range[3]) {
+                return `${range[0]}.${range[1]}`;
+            }
+            else {
+                return `${range[0]}.${range[1]}-${range[3]}`;
+            }
+        }
+        return `${range[0]}.${range[1]}-${range[2]}.${range[3]}`;
+    },
+    /**
+     * Returns the start position of a source range.
+     */
+    getStart(range) {
+        return [range[0], range[1]];
+    },
+    /**
+     * Returns the start line of a source range.
+     */
+    getStartLine(range) {
+        return range[0];
+    },
+    /**
+     * Returns the end position of a source range.
+     */
+    getEnd(range) {
+        return [range[2], range[3]];
+    },
+    /**
+     * Returns the end line of a source range.
+     */
+    getEndLine(range) {
+        return range[2];
+    },
+    /**
+     * Creates a source range from the given line and column numbers.
+     * @param sl - start line
+     * @param sc - start column
+     * @param el - end line
+     * @param ec - end column
+     */
+    from(sl, sc, el = sl, ec = sc) {
+        return [Number(sl), Number(sc), Number(el), Number(ec)];
+    },
+    /**
+     * returns an invalid source range
+     */
+    invalid() {
+        return [-1, -1, -1, -1];
+    },
+    /**
+     * Merges multiple source ranges into a single source range that spans from the earliest start to the latest end.
+     * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
+     * @throws if no ranges are provided
+     */
+    merge(rs) {
+        const rsSafe = rs.filter(assert_1.isNotUndefined);
+        (0, assert_1.guard)(rsSafe.length > 0, 'Cannot merge no ranges');
+        return rsSafe.reduce(([sl, sc, el, ec], [nsl, nsc, nel, nec]) => [
+            ...(sl < nsl || (sl === nsl && sc < nsc) ? [sl, sc] : [nsl, nsc]),
+            ...(el > nel || (el === nel && ec > nec) ? [el, ec] : [nel, nec])
+        ], rsSafe[0]);
+    },
+    /**
+     * @returns true iff `r1` starts and ends before `r2` starts (i.e., if `r1` and `r2` do not overlap and `r1` comes before `r2`
+     */
+    startsCompletelyBefore([, , r1el, r1ec], [r2sl, r2sc, ,]) {
+        return r1el < r2sl || (r1el === r2sl && r1ec < r2sc);
+    },
+    /**
+     * Checks if the two ranges overlap.
+     */
+    overlap([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
+        return r1sl <= r2el && r2sl <= r1el && r1sc <= r2ec && r2sc <= r1ec;
+    },
+    /**
+     * Calculates the component-wise sum of two ranges.
+     */
+    add([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
+        return [r1sl + r2sl, r1sc + r2sc, r1el + r2el, r1ec + r2ec];
+    },
+    /**
+     * Provides a comparator for {@link SourceRange}s that sorts them in ascending order.
+     * @returns a positive number if `r1` comes after `r2`, a negative number if `r1` comes before `r2`, and `0` if they are equal
+     */
+    compare([r1sl, r1sc, ,], [r2sl, r2sc, ,]) {
+        if (r1sl === r2sl) {
+            return r1sc - r2sc;
+        }
+        else {
+            return r1sl - r2sl;
+        }
+    },
+    /**
+     * Checks if the first range is a subset of the second range.
+     */
+    isSubsetOf([r1sl, r1sc, r1el, r1ec], [r2sl, r2sc, r2el, r2ec]) {
+        return (r1sl > r2sl || r1sl === r2sl && r1sc >= r2sc) && (r1el < r2el || r1sl === r2sl && r1ec <= r2ec);
+    },
+    /**
+     * Combines overlapping or subset ranges into a minimal set of ranges.
+     * @see {@link SourceRange.merge} for merging multiple ranges into a single range.
+     */
+    combineRanges(...ranges) {
+        return ranges.filter(range => !ranges.some(other => range !== other && exports.SourceRange.isSubsetOf(range, other)));
+    },
+    fromNode(node) {
+        return node?.info.fullRange ?? node?.location;
+    }
+};
 /**
- * Combines overlapping or subset ranges into a minimal set of ranges.
- * If you are interested in merging overlapping ranges, see {@link mergeRanges}.
+ * Utility functions for {@link SourceLocation|source locations}.
  */
-function combineRanges(...ranges) {
-    return ranges.filter(range => !ranges.some(other => range !== other && rangeIsSubsetOf(range, other)));
-}
+exports.SourceLocation = {
+    /**
+     * Formats a {@link SourceLocation|source location} as a human-readable string.
+     */
+    format(location) {
+        if (location === undefined) {
+            return '??:??-??';
+        }
+        else if (location[4] !== undefined) {
+            return `${location[4]}:${exports.SourceRange.format(location)}`;
+        }
+        else {
+            return exports.SourceRange.format(location);
+        }
+    },
+    /**
+     * Returns the {@link SourceRange|source range} part of a {@link SourceLocation|source location}.
+     */
+    getRange(location) {
+        return location;
+    },
+    getFile(location) {
+        return location[4];
+    },
+    /**
+     * Returns the file part of a {@link SourceLocation|source location}, or `undefined` if no file is set.
+     */
+    from(range, file) {
+        return file !== undefined ? [...range, file] : range;
+    },
+    /**
+     * Creates a {@link SourceLocation|source location} from a {@link SourceRange|source range} and a file name.
+     * @returns undefined if the given range is undefined
+     * @see {@link SourceRange.fromNode} for getting the range from an AST node
+     */
+    fromNode(node) {
+        const range = exports.SourceRange.fromNode(node);
+        return range !== undefined ? exports.SourceLocation.from(range, node.info.file) : undefined;
+    },
+    /**
+     * Maps the file part of a {@link SourceLocation|source location} using the given mapper function.
+     */
+    mapFile(loc, fileMapper) {
+        const range = exports.SourceLocation.getRange(loc);
+        const file = loc[4];
+        return exports.SourceLocation.from(range, fileMapper(file));
+    },
+    /**
+     * Checks if the first location is a subset of the second location.
+     * For this, they must be in the same file!
+     * @see {@link SourceRange.isSubsetOf}
+     */
+    isSubsetOf(loc1, loc2) {
+        if (exports.SourceLocation.getFile(loc1) !== exports.SourceLocation.getFile(loc2)) {
+            return false;
+        }
+        return exports.SourceRange.isSubsetOf(exports.SourceLocation.getRange(loc1), exports.SourceLocation.getRange(loc2));
+    },
+    compare(loc1, loc2) {
+        const res = exports.SourceRange.compare(exports.SourceLocation.getRange(loc1), exports.SourceLocation.getRange(loc2));
+        if (res !== 0) {
+            return res;
+        }
+        const file1 = exports.SourceLocation.getFile(loc1);
+        const file2 = exports.SourceLocation.getFile(loc2);
+        if (file1 === file2) {
+            return 0;
+        }
+        else if (file1 === undefined) {
+            return -1;
+        }
+        else if (file2 === undefined) {
+            return 1;
+        }
+        else {
+            return file1 < file2 ? -1 : 1;
+        }
+    },
+    /**
+     * Returns an invalid source location (i.e., with an invalid range and no file).
+     */
+    invalid() {
+        return exports.SourceRange.invalid();
+    },
+    /**
+     * Merges multiple source locations into a single source location that spans from the earliest start to the latest end.
+     * If the locations are from different files, `undefined` is returned.
+     * Files may be `undefined` themselves, but if there is at least one defined file, they must all be the same defined file for the merge to succeed.
+     */
+    merge(locs) {
+        const locsSafe = locs.filter(assert_1.isNotUndefined);
+        if (locsSafe.length === 0) {
+            return undefined;
+        }
+        const firstFile = locsSafe.find(loc => loc[4] !== undefined)?.[4];
+        if (locsSafe.some(loc => loc[4] !== undefined && loc[4] !== firstFile)) {
+            return undefined;
+        }
+        return exports.SourceLocation.from(exports.SourceRange.merge(locsSafe.map(exports.SourceLocation.getRange)), firstFile);
+    }
+};
 //# sourceMappingURL=range.js.map

package/util/version.js

@@ -6,7 +6,7 @@ exports.printVersionInformation = printVersionInformation;
 const semver_1 = require("semver");
 const assert_1 = require("./assert");
 // this is automatically replaced with the current version by release-it
-const version = '2.9.2';
+const version = '2.9.3';
 /**
  * Retrieves the current flowR version as a new {@link SemVer} object.
  */