On Wed, Mar 22 2023, Glen Choo wrote:
> Every time I try to read cocci and spatch docs, I'm impressed at how
> impenetrable they are ;)
FWIW you should ignore the manpage, which and instead read the
"Coccinelle User’s manual", and particularly "The SmPL Grammar", both of
which are available as PDFs on their website.
But their docs are rather terse, and sometimes even incomplete. I've
often resorted to grepping their own test cases to figure out how
something works.
> Nevertheless, I'd still like to understand how
> the pattern works. I'll take a stab in the dark, and perhaps you can
> correct me.
>
> Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes:
>
>> +(
>> +- read_object_file
>> ++ repo_read_object_file
>> +|
>> +- has_object_file
>> ++ repo_has_object_file
>> +|
>> +- has_object_file_with_flags
>> ++ repo_has_object_file_with_flags
>> +|
>> +- parse_commit_internal
>> ++ repo_parse_commit_internal
>> +|
>> +- parse_commit
>> ++ repo_parse_commit
>> +|
>> +- get_merge_bases
>> ++ repo_get_merge_bases
>> +|
>> +- get_merge_bases_many
>> ++ repo_get_merge_bases_many
>> +|
>> +- get_merge_bases_many_dirty
>> ++ repo_get_merge_bases_many_dirty
>> +|
>> +- in_merge_bases
>> ++ repo_in_merge_bases
>> +|
>> +- in_merge_bases_many
>> ++ repo_in_merge_bases_many
>> +|
>> +- get_commit_buffer
>> ++ repo_get_commit_buffer
>> +|
>> +- unuse_commit_buffer
>> ++ repo_unuse_commit_buffer
>> +|
>> +- logmsg_reencode
>> ++ repo_logmsg_reencode
>> +|
>> +- format_commit_message
>> ++ repo_format_commit_message
>> +)
>
> I assume that `|` characters in parentheses are a logical OR, and each
> of the expressions checks for the `-` side in the original and replaces
> it with the `+` side.
Yes, just a simple "replace A with B".
>> + (
>> ++ the_repository,
>> + ...)
>
> Then this is another expression that matches literal `()` after the
> previous expression? `+the_repository` adds `the_repository` right after
> the opening `(`, then leaves the uninteresting `...` in place.
>
> If so, I don't know how cocci/spatch tells the difference between
> literal `()` vs an expression in the syntax (preceding whitespace?).
Yes, whitespace is significant in the coccinelle syntax, generally its
own "()" grouping goes at the beginning of a line, wheras you indent
program text in the "diff" with whitespace.
E.g. our equals-null.cocci has two rules that use "(" and ")" in a way
that would be ambiguous if this whitespace-disambiguation weren't being
used.
