Examples with Example com.google.copybara.doc.annotations.Example used on opensource projects

Example 1 with Example

use of com.google.copybara.doc.annotations.Example in project copybara by google.

the class Core method filterReplace.

@SuppressWarnings("unused")
@StarlarkMethod(name = "filter_replace", doc = "Applies an initial filtering to find a substring to be replaced and then applies" + " a `mapping` of replaces for the matched text.", parameters = { @Param(name = "regex", named = true, doc = "A re2 regex to match a substring of the file", allowedTypes = { @ParamType(type = String.class) }), @Param(name = "mapping", named = true, doc = "A mapping function like core.replace_mapper or a dict with mapping values.", defaultValue = "{}"), @Param(name = "group", named = true, allowedTypes = { @ParamType(type = StarlarkInt.class), @ParamType(type = NoneType.class) }, doc = "Extract a regex group from the matching text and pass this as parameter to" + " the mapping instead of the whole matching text.", defaultValue = "None"), @Param(name = "paths", named = true, allowedTypes = { @ParamType(type = Glob.class), @ParamType(type = NoneType.class) }, doc = "A glob expression relative to the workdir representing the files to apply the" + " transformation. For example, glob([\"**.java\"]), matches all java files" + " recursively. Defaults to match all the files recursively.", defaultValue = "None"), @Param(name = "reverse", named = true, allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "A re2 regex used as reverse transformation", defaultValue = "None") }, useStarlarkThread = true)
@DocDefault(field = "paths", value = "glob([\"**\"])")
@DocDefault(field = "reverse", value = "regex")
@DocDefault(field = "group", value = "Whole text")
@Example(title = "Simple replace with mapping", before = "Simplest mapping", code = SIMPLE_FILTER_REPLACE_EXAMPLE)
@Example(title = "TODO replace", before = "This replace is similar to what it can be achieved with core.todo_replace:", code = TODO_FILTER_REPLACE_EXAMPLE)
public FilterReplace filterReplace(String regex, Object mapping, Object group, Object paths, Object reverse, StarlarkThread thread) throws EvalException {
    ReversibleFunction<String, String> func = getMappingFunction(mapping);
    String afterPattern = convertFromNoneable(reverse, regex);
    int numGroup = convertFromNoneable(group, StarlarkInt.of(0)).toInt("group");
    Pattern before = Pattern.compile(regex);
    check(numGroup <= before.groupCount(), "group idx is greater than the number of groups defined in '%s'. Regex has %s groups", before.pattern(), before.groupCount());
    Pattern after = Pattern.compile(afterPattern);
    check(numGroup <= after.groupCount(), "reverse_group idx is greater than the number of groups defined in '%s'." + " Regex has %s groups", after.pattern(), after.groupCount());
    return new FilterReplace(workflowOptions, before, after, numGroup, numGroup, func, convertFromNoneable(paths, Glob.ALL_FILES), thread.getCallerLocation());
}

Example 2 with Example

use of com.google.copybara.doc.annotations.Example in project copybara by google.

the class FormatModule method buildifier.

@StarlarkMethod(name = "buildifier", doc = "Formats the BUILD files using buildifier.", parameters = { @Param(name = "paths", allowedTypes = { @ParamType(type = Glob.class), @ParamType(type = NoneType.class) }, doc = "Paths of the files to format relative to the workdir.", defaultValue = "None", named = true), @Param(name = "type", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "The type of the files. Can be 'auto', 'bzl', 'build' or 'workspace'. Note that" + " this is not recommended to be set and might break in the future. The" + " default is 'auto'. This mode formats as BUILD files \"BUILD\"," + " \"BUILD.bazel\", \"WORKSPACE\" and \"WORKSPACE.bazel\" files. The rest as" + " bzl files. Prefer to use those names for BUILD files instead of setting" + " this flag.", defaultValue = "'auto'", named = true), @Param(name = "lint", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "If buildifier --lint should be used. This fixes several common issues. Note that" + " this transformation is difficult to revert. For example if it removes a" + " load statement because is not used after removing a rule, then the reverse" + " workflow needs to add back the load statement (core.replace or similar). " + " Possible values: `OFF`, `FIX`. Default is `OFF`", defaultValue = "None", named = true), @Param(name = "lint_warnings", allowedTypes = { @ParamType(type = Sequence.class, generic1 = String.class) }, defaultValue = "[]", doc = "Warnings used in the lint mode. Default is buildifier default`", named = true) })
@DocDefault(field = "lint", value = "\"OFF\"")
@UsesFlags(BuildifierOptions.class)
@Example(title = "Default usage", before = "The default parameters formats all BUILD and bzl files in the checkout directory:", code = "format.buildifier()")
@Example(title = "Enable lint", before = "Enable lint for buildifier", code = "format.buildifier(lint = \"FIX\")")
@Example(title = "Using globs", before = "Globs can be used to match only certain files:", code = "format.buildifier(\n" + "    paths = glob([\"foo/BUILD\", \"foo/**/BUILD\"], exclude = [\"foo/bar/BUILD\"])" + "\n)", after = "Formats all the BUILD files inside `foo` except for `foo/bar/BUILD`")
@DocDefault(field = "paths", value = "glob([\"**.bzl\", \"**/BUILD\", \"BUILD\"])")
public Transformation buildifier(// <String>
Object paths, // <String>
Object type, // <String>
Object lint, // <String>
Sequence<?> warnings) throws EvalException {
    String typeStr = convertFromNoneable(type, null);
    if (typeStr != null) {
        check(BUILDIFIER_TYPE_VALUES.contains(typeStr), "Non-valid type: %s. Valid types: %s", typeStr, BUILDIFIER_TYPE_VALUES);
    }
    LintMode lintMode = stringToEnum("lint", convertFromNoneable(lint, "OFF"), LintMode.class);
    check(lintMode != LintMode.OFF || warnings.isEmpty(), "Warnings can only be used when lint is set to FIX");
    return new BuildifierFormat(buildifierOptions, generalOptions, convertFromNoneable(paths, DEFAULT_BUILDIFIER_PATHS), lintMode, ImmutableList.copyOf(Sequence.cast(warnings, String.class, "lint_warnings")), typeStr);
}

Example 3 with Example

use of com.google.copybara.doc.annotations.Example in project copybara by google.

the class GitModule method githubPrDestination.

@SuppressWarnings("unused")
@StarlarkMethod(name = "github_pr_destination", doc = "Creates changes in a new pull request in the destination.", parameters = { @Param(name = "url", named = true, doc = "Url of the GitHub project. For example" + " \"https://github.com/google/copybara'\""), @Param(name = "destination_ref", named = true, doc = "Destination reference for the change.", defaultValue = "'master'"), @Param(name = "pr_branch", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, defaultValue = "None", named = true, positional = false, doc = "Customize the pull request branch. Any variable present in the message in the " + "form of ${CONTEXT_REFERENCE} will be replaced by the corresponding stable " + "reference (head, PR number, Gerrit change number, etc.)."), @Param(name = "partial_fetch", defaultValue = "False", named = true, positional = false, doc = "This is an experimental feature that only works for certain origin globs."), @Param(name = "allow_empty_diff", defaultValue = "True", named = true, positional = false, doc = "By default, copybara migrates changes without checking existing PRs. " + "If set, copybara will skip pushing a change to an existing PR " + "only if the git three of the pending migrating change is the same " + "as the existing PR."), @Param(name = "title", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, defaultValue = "None", named = true, positional = false, doc = "When creating (or updating if `update_description` is set) a pull request, use" + " this title. By default it uses the change first line. This field accepts" + " a template with labels. For example: `\"Change ${CONTEXT_REFERENCE}\"`"), @Param(name = "body", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, defaultValue = "None", named = true, positional = false, doc = "When creating (or updating if `update_description` is set) a pull request, use" + " this body. By default it uses the change summary. This field accepts" + " a template with labels. For example: `\"Change ${CONTEXT_REFERENCE}\"`"), @Param(name = "integrates", allowedTypes = { @ParamType(type = Sequence.class, generic1 = GitIntegrateChanges.class), @ParamType(type = NoneType.class) }, named = true, defaultValue = "None", doc = "Integrate changes from a url present in the migrated change" + " label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is" + " present in the message", positional = false), @Param(name = "api_checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker for the GitHub API endpoint provided for after_migration hooks. " + "This field is not required if the workflow hooks don't use the " + "origin/destination endpoints.", named = true, positional = false), @Param(name = "update_description", defaultValue = "False", named = true, positional = false, doc = "By default, Copybara only set the title and body of the PR when creating" + " the PR. If this field is set to true, it will update those fields for" + " every update."), @Param(name = "primary_branch_migration", defaultValue = "False", named = true, positional = false, doc = "When enabled, copybara will ignore the 'desination_ref' param if it is 'master' or" + " 'main' and instead try to establish the default git branch. If this fails," + " it will fall back to the param's declared value.\n" + "This is intended to help migrating to the new standard of using 'main'" + " without breaking users relying on the legacy default."), @Param(name = "checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker that validates the commit files & message. If `api_checker` is not" + " set, it will also be used for checking API calls. If only `api_checker`" + "is used, that checker will only apply to API calls.", named = true, positional = false) }, useStarlarkThread = true)
@UsesFlags({ GitDestinationOptions.class, GitHubDestinationOptions.class })
@Example(title = "Common usage", before = "Create a branch by using copybara's computerIdentity algorithm:", code = "git.github_pr_destination(\n" + "        url = \"https://github.com/google/copybara\",\n" + "        destination_ref = \"master\",\n" + "    )")
@Example(title = "Using pr_branch with label", before = "Customize pr_branch with context reference:", code = "git.github_pr_destination(\n" + "        url = \"https://github.com/google/copybara\",\n" + "         destination_ref = \"master\",\n" + "         pr_branch = 'test_${CONTEXT_REFERENCE}',\n" + "    )")
@Example(title = "Using pr_branch with constant string", before = "Customize pr_branch with a constant string:", code = "git.github_pr_destination(\n" + "        url = \"https://github.com/google/copybara\",\n" + "        destination_ref = \"master\",\n" + "        pr_branch = 'test_my_branch',\n" + "    )")
public GitHubPrDestination githubPrDestination(String url, String destinationRef, Object prBranch, Boolean partialFetch, Boolean allowEmptyDiff, Object title, Object body, Object integrates, Object apiChecker, Boolean updateDescription, Boolean primaryBranchMigrationMode, Object checker, StarlarkThread thread) throws EvalException {
    GeneralOptions generalOptions = options.get(GeneralOptions.class);
    // This restricts to github.com, we will have to revisit this to support setups like GitHub
    // Enterprise.
    check(GITHUB_COM.isGitHubUrl(url), "'%s' is not a valid GitHub url", url);
    GitDestinationOptions destinationOptions = options.get(GitDestinationOptions.class);
    GitHubOptions gitHubOptions = options.get(GitHubOptions.class);
    String destinationPrBranch = convertFromNoneable(prBranch, null);
    Checker apiCheckerObj = convertFromNoneable(apiChecker, null);
    Checker checkerObj = convertFromNoneable(checker, null);
    return new GitHubPrDestination(fixHttp(checkNotEmpty(firstNotNull(destinationOptions.url, url), "url"), thread.getCallerLocation()), destinationRef, convertFromNoneable(prBranch, null), partialFetch, generalOptions, options.get(GitHubOptions.class), destinationOptions, options.get(GitHubDestinationOptions.class), options.get(GitOptions.class), new GitHubPrWriteHook(generalOptions, url, gitHubOptions, destinationPrBranch, partialFetch, allowEmptyDiff, getGeneralConsole(), GITHUB_COM), Starlark.isNullOrNone(integrates) ? defaultGitIntegrate : Sequence.cast(integrates, GitIntegrateChanges.class, "integrates"), convertFromNoneable(title, null), convertFromNoneable(body, null), mainConfigFile, apiCheckerObj != null ? apiCheckerObj : checkerObj, updateDescription, GITHUB_COM, primaryBranchMigrationMode, checkerObj);
}

Example 4 with Example

use of com.google.copybara.doc.annotations.Example in project copybara by google.

the class ExamplesTest method checkExamples.

private ImmutableList<Result> checkExamples(SkylarkTestExecutor executor, Class<?> module, ImmutableList<Example> samples, String name) {
    ImmutableList.Builder<Result> result = ImmutableList.builder();
    for (Example example : samples) {
        Object val;
        String exampleRef = module.getName() + "#" + name + ": " + example.title();
        // Quilt requires an extra file.
        if (exampleRef.contains("com.google.copybara.transform.patch.PatchModule#quiltApply")) {
            executor.addConfigFile("patches/series", "");
        }
        try {
            val = Strings.isNullOrEmpty(example.testExistingVariable()) ? executor.eval("a", "a=" + example.code()) : executor.eval(example.testExistingVariable(), example.code());
            assertWithMessage(exampleRef).that(val).isNotNull();
            result.add(new Result(exampleRef, module, null));
        } catch (ValidationException | AssertionError e) {
            result.add(new Result(exampleRef, module, e));
        }
    }
    return result.build();
}

Example 5 with Example

use of com.google.copybara.doc.annotations.Example in project copybara by google.

the class MarkdownGenerator method generateFunctionDocumentation.

private CharSequence generateFunctionDocumentation(TypeElement module, SkylarkModule skyModule, Element member) throws ElementException {
    StringBuilder sb = new StringBuilder();
    AnnotationHelper<SkylarkSignature> signature = annotationHelper(member, SkylarkSignature.class);
    if (signature == null || !(member instanceof VariableElement)) {
        return sb;
    }
    if (!signature.ann.documented()) {
        return sb;
    }
    String functionName = signature.ann.name();
    DeclaredType objectType = signature.getClassValue("objectType");
    if (objectType.toString().equals(module.toString())) {
        functionName = skyModule.name() + "." + functionName;
    }
    sb.append("<a id=\"").append(functionName).append("\" aria-hidden=\"true\"></a>\n");
    sb.append("### ").append(functionName).append("\n\n");
    sb.append(signature.ann.doc());
    sb.append("\n\n");
    // Create a string like `Origin foo(param, param2=Default)`
    sb.append("`");
    String returnTypeStr = skylarkTypeName(signature.getClassValue("returnType"));
    if (!returnTypeStr.equals("")) {
        sb.append(returnTypeStr).append(" ");
    }
    sb.append(functionName).append("(");
    List<AnnotationValue> params = signature.getValue("parameters");
    StringBuilder longDescription = new StringBuilder();
    int startIndex = firstParamIsSelf(module, skyModule, objectType) ? 1 : 0;
    for (int i = startIndex; i < params.size(); i++) {
        AnnotationHelper<Param> param = new AnnotationHelper<>(signature.ann.parameters()[i], (AnnotationMirror) params.get(i).getValue(), member);
        if (i > startIndex) {
            sb.append(", ");
        }
        sb.append(param.ann.name());
        String defaultValue = param.ann.defaultValue();
        if (!defaultValue.isEmpty()) {
            sb.append("=").append(defaultValue);
        }
        longDescription.append(param.ann.name()).append("|");
        longDescription.append("`").append(skylarkTypeNameGeneric(param.getClassValue("type"), param.getClassValue("generic1"))).append("`").append("<br><p>");
        longDescription.append(param.ann.doc());
        longDescription.append("</p>");
        longDescription.append("\n");
    }
    sb.append(")`\n\n");
    if (longDescription.length() > 0) {
        sb.append("#### Parameters:\n\n");
        sb.append("Parameter | Description\n");
        sb.append("--------- | -----------\n");
        sb.append(longDescription);
        sb.append("\n\n");
    }
    // Generate flags associated with an specific method
    sb.append(generateFlagsInfo(member));
    AnnotationHelper<Examples> examples = annotationHelper(member, Examples.class);
    AnnotationHelper<Example> singleExample = annotationHelper(member, Example.class);
    if (examples != null) {
        sb.append("#### Examples:\n\n");
        for (Example example : examples.ann.value()) {
            printExample(sb, example);
        }
    } else if (singleExample != null) {
        sb.append("#### Example:\n\n");
        printExample(sb, singleExample.ann);
    }
    return sb;
}