@atomist/automation-client/lib/tree/ast/astUtils.d.ts

Atomist API for software low-level client

import { FunctionRegistry, PathExpression } from "@atomist/tree-path";
import { File } from "../../project/File";
import { Project, ProjectAsync } from "../../project/Project";
import { GlobOptions } from "../../project/util/projectUtils";
import { LocatedTreeNode } from "../LocatedTreeNode";
import { FileHit, MatchResult, NodeReplacementOptions } from "./FileHits";
import { FileParser } from "./FileParser";
import { FileParserRegistry } from "./FileParserRegistry";
/**
 * Create a MatchTester to use against this file, caching
 * any parsed or otherwise computed resources.
 */
export declare type MatchTesterMaker = (f: File) => Promise<MatchTester>;
/**
 * Options for performing a path expression query against a project
 */
export interface PathExpressionQueryOptions {
    /**
     * Parser or parsers to use to parse files
     */
    parseWith: FileParser | FileParserRegistry;
    /**
     * Glob pattern or patterns describing files to match
     */
    globPatterns: GlobOptions;
    /**
     * Path expression to execute
     */
    pathExpression: string | PathExpression;
    /** functionRegistry registry to look for path expression functions in */
    functionRegistry?: FunctionRegistry;
    /**
     * Optional filter to exclude files before parse phase. This can increase efficiency
     * by preventing unnecessary parsing.
     */
    fileFilter?: (f: File) => Promise<boolean>;
    /**
     * Optionally return a tester for matches in this file, testing the node backing the match.
     * This can be useful for contextual testing: E.g. testing if one match is within another.
     * @param {File} f
     * @return {Promise<MatchTester>}
     */
    testWith?: MatchTesterMaker;
    /**
     * Whether to cache the AST for the given parser for this file.
     * Caching will occur unless this property is explicitly set to false.
     * Disable caching if many files are likely to be parsed as one offs.
     */
    cacheAst?: boolean;
}
/**
 * Tests matches within this file, using their tree node basis.
 */
export declare type MatchTester = (n: LocatedTreeNode) => boolean;
/**
 * Integrate path expressions with project operations to find all matches
 * @param p project
 * @param parseWith parser or parsers to use to parse files
 * @param globPatterns file glob patterns
 * @param pathExpression path expression string or parsed
 * @param functionRegistry registry to look for path expression functions in
 * @return {Promise<MatchResult[]>} matches
 * @type T match type to mix in
 * @deprecated use matches
 */
export declare function findMatches<T>(p: ProjectAsync, parseWith: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, functionRegistry?: FunctionRegistry): Promise<Array<MatchResult & T>>;
/**
 * Integrate path expressions with project operations to find all matches
 * @param p project
 * @param peqo query options
 * @return {Promise<MatchResult[]>} matches
 * @type T match type to mix in
 */
export declare function matches<T>(p: ProjectAsync, peqo: PathExpressionQueryOptions): Promise<Array<MatchResult & T>>;
/**
 * Generator style iteration over matches in a project.
 * Modifications made to matches will be made on the project.
 * @param p project
 * @param opts options for query
 * @type T match type to mix in
 */
export declare function matchIterator<T>(p: Project, opts: PathExpressionQueryOptions): AsyncIterable<MatchResult & T>;
/**
 * Integrate path expressions with project operations to gather mapped values from all matches.
 * Choose the files with globPatterns; choose the portions of code to match with the pathExpression.
 * Choose what to return based on each match with the mapper function.
 * Returns all of the values returned by the mapper (except undefined).
 * @param p project
 * @param parserOrRegistry parser or parsers to use to parse files
 * @param globPatterns file glob patterns
 * @param mapper mapping function from match result to result
 * @param pathExpression path expression string or parsed
 * @param functionRegistry registry to look for path expression functions in
 * @return {Promise<MatchResult[]>} matches
 * @deprecated use gather
 */
export declare function gatherFromMatches<T>(p: ProjectAsync, parserOrRegistry: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, mapper: (m: MatchResult) => T, functionRegistry?: FunctionRegistry): Promise<T[]>;
/**
 * Integrate path expressions with project operations to gather mapped values from all matches.
 * Choose the files with globPatterns; choose the portions of code to match with the pathExpression.
 * Choose what to return based on each match with the mapper function.
 * Returns all of the values returned by the mapper (except undefined).
 * @param p project
 * @param peqo options
 * @return {Promise<MatchResult[]>} matches
 */
export declare function gather<T>(p: ProjectAsync, peqo: PathExpressionQueryOptions & {
    mapper: (m: MatchResult) => T;
}): Promise<T[]>;
/**
 * A match within a project, including location information
 */
export interface Gathered<T> {
    readonly value: T;
    readonly file: File;
    /**
     * Raw match result
     */
    readonly matchResult: MatchResult;
}
/**
 * Like gather but keep location
 */
export declare function gatherWithLocation<T>(p: ProjectAsync, peqo: PathExpressionQueryOptions & {
    mapper: (m: MatchResult) => T;
}): Promise<Array<Gathered<T>>>;
/**
 * Integrate path expressions with project operations to find all matches
 * and their files
 * @param p project
 * @param parseWith parser or parsers to use to parse files
 * @param globPatterns file glob patterns
 * @param pathExpression path expression string or parsed
 * @param functionRegistry registry to look for path expression functions in
 * @return hits for each file
 * @deprecated use fileMatches
 */
export declare function findFileMatches(p: ProjectAsync, parseWith: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, functionRegistry?: FunctionRegistry): Promise<FileHit[]>;
/**
 * Integrate path expressions with project operations to find all matches
 * and their files
 * @param p project
 * @param peqo query options
 * @return hits for each file
 */
export declare function fileMatches(p: ProjectAsync, peqo: PathExpressionQueryOptions): Promise<FileHit[]>;
export interface PathExpressionFileHits {
    fileHits: FileHit[];
    pathExpression: string;
}
/**
 * Iterate over provided path expression query options and return
 * [[FileHit]]s for each path expression.
 * @param p project
 * @param peqos Array of query options
 * @return hits for each file for each query option
 */
export declare function pathExpressionFileMatches(p: ProjectAsync, peqos: PathExpressionQueryOptions[]): Promise<PathExpressionFileHits[]>;
/**
 * Generator style iteration over file matches
 * @param p project
 * @param opts options for query
 */
export declare function fileHitIterator(p: Project, opts: PathExpressionQueryOptions): AsyncIterable<FileHit>;
/**
 * Convenient method to find all values of matching nodes--
 * typically, terminals such as identifiers
 * @param p project
 * @param globPatterns file glob pattern
 * @param parserOrRegistry parser for files
 * @param pathExpression path expression string or parsed
 * @param functionRegistry registry to look for path expression functions in
 * @return {Promise<TreeNode[]>} hit record for each matching file
 */
export declare function findValues(p: ProjectAsync, parserOrRegistry: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, functionRegistry?: FunctionRegistry): Promise<string[]>;
/**
 * Integrate path expressions with project operations to find all matches
 * of a path expression and zap them. Use with care!
 * @param p project
 * @param globPatterns file glob pattern
 * @param parserOrRegistry parser for files
 * @param pathExpression path expression string or parsed
 * @param opts options for handling whitespace
 * @return {Promise<TreeNode[]>} hit record for each matching file
 */
export declare function zapAllMatches<P extends ProjectAsync = ProjectAsync>(p: P, parserOrRegistry: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, opts?: NodeReplacementOptions): Promise<P>;
/**
 * Integrate path expressions with project operations to find all matches
 * of a path expression and perform a mutation on them them. Use with care!
 * @param p project
 * @param globPatterns file glob pattern
 * @param parserOrRegistry parser for files
 * @param pathExpression path expression string or parsed
 * @param action what to do with matches
 * @return {Promise<TreeNode[]>} hit record for each matching file
 */
export declare function doWithAllMatches<P extends ProjectAsync = ProjectAsync>(p: P, parserOrRegistry: FileParser | FileParserRegistry, globPatterns: GlobOptions, pathExpression: string | PathExpression, action: (m: MatchResult) => void): Promise<P>;
export declare function findParser(pathExpression: PathExpression, fp: FileParser | FileParserRegistry): FileParser;
/**
 * Return literal values that must be present in a file for this path expression to
 * match. Return the empty array if there are no literal @values or if we cannot
 * determine whether there may be for this path expression.
 * @param {PathExpression} pex
 * @return {string[]}
 */
export declare function literalValues(pex: PathExpression): string[];
//# sourceMappingURL=astUtils.d.ts.map