@atomist/rug/model/File.ts

TypeScript model for Atomist Rugs, see http://docs.atomist.com/

/*
 * Copyright 2015-2017 Atomist Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { TreeNode, GraphNode, FormatInfo, PathExpressionEngine } from "@atomist/rug/tree/PathExpression";
import { ProjectContext } from "@atomist/rug/operations/ProjectEditor";
import { FileArtifactBacked } from "./FileArtifactBacked";
import { MutableView } from "./MutableView";
export { File };

/**
 * Type for a file within a project.
 */
interface File extends FileArtifactBacked, MutableView {

    /**
     * Append the given content to the file
     *
     * @param literal {string} The string to append
     */
    append(literal: string): void;

    /**
     * Does the file content contain the given string?
     *
     * @param what {string} The string to use when looking for it in the file
     * @returns {boolean}
     */
    contains(what: string): boolean;

    /**
     * Does the file content contain a match for the given regex
     *
     * @param regexp {string} The regular expression to look for in the file's content
     * @returns {boolean}
     */
    containsMatch(regexp: string): boolean;

    /**
     * Return all matches for the given regexp in this file
     *
     * @param regexp {string} The regular expression to search for
     * @returns {string[]}
     */
    findMatches(regexp: string): string[];

    /**
     * Return the first match for the given regex, or the empty string if not found. Call containsMatch first to check presence.
     *
     * @param regexp {string} The regular expression to search for
     * @returns {string}
     */
    firstMatch(regexp: string): string;

    /**
     * DEPRECATED - Is this a Java file?
     *
     * @property {boolean} isJava
     */
    readonly isJava: boolean;

    /**
     * DEPRECATED - Is this a Scala file?
     *
     * @property {boolean} isScala
     */
    readonly isScala: boolean;

    /**
     * If the file already contains the specified text, does nothing. Otherwise appends it to the file
     *
     * @param content {string} The content that the file will contain
     */
    mustContain(content: string): void;

    /**
     * Name of the file, excluding path
     *
     * @property {string} name
     */
    readonly name: string;

    /**
     * DEPRECATED - Does the file name (not path) contain the given string?
     *
     * @param what {string} The string to use when looking for it in the file name or path
     * @returns {boolean}
     */
    nameContains(what: string): boolean;

    /**
     * Prepend the given content to the file
     *
     * @param literal {string} The string to prepend to the file
     */
    prepend(literal: string): void;

    /**
     * Replace all occurrences of the given regexp in this file
     *
     * @param regexp {string} The regular expression to search for
     * @param replaceWith {string} The string to replace matching expressions with
     */
    regexpReplace(regexp: string, replaceWith: string): void;

    /**
     * Replace all instances of the given literal string in this file
     *
     * @param literal {string} The string to search for
     * @param replaceWith {string} The string to replace the matches with
     */
    replace(literal: string, replaceWith: string): void;

    /**
     * Set entire file content to new string
     *
     * @param newContent {string} The content to set the file to
     */
    setContent(newContent: string): void;

    /**
     * Set the file name, not path, to the given value
     *
     * @param name {string} The name to set the file to
     */
    setName(name: string): void;

    /**
     * Change the path to the given value. Path should use forward slashes to denote directories
     *
     * @param newPath {string} The path to change the file to
     */
    setPath(newPath: string): void;

}