Skip to content

[doc] perlop: splitting of the section about 'or' and 'xor' #18565

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
rsFalse opened this issue Feb 12, 2021 · 1 comment · Fixed by #23286
Closed

[doc] perlop: splitting of the section about 'or' and 'xor' #18565

rsFalse opened this issue Feb 12, 2021 · 1 comment · Fixed by #23286

Comments

@rsFalse
Copy link

rsFalse commented Feb 12, 2021

Where
https://perldoc.perl.org/perlop#Logical-or-and-Exclusive-Or

Description
I suggest to split this section into two. Reason is that 'or' differs from 'xor' significantly: 1) can/cannot short-circuit, 2) 'xor' returns Perl's TRUE or FALSE i.e. 1 or 0/'', and 'or' returns differently (LEFT: evaluated expression; RIGHT: (evaluated?)expression with context propagation from outside). These operators look similarly (and, or, xor), but 'xor' behaves differently. Splitting needed for emphasis of difference.

(This is almost a copy of my suggestions which I wrote earlier to perlmonks https://perlmonks.org/?node_id=11128119)

@rsFalse rsFalse changed the title [doc] [doc] perlop: splitting of the section about 'or' and 'xor' Feb 12, 2021
@jkeenan
Copy link
Contributor

jkeenan commented Feb 20, 2021

Where
https://perldoc.perl.org/perlop#Logical-or-and-Exclusive-Or

Description
I suggest to split this section into two. Reason is that 'or' differs from 'xor' significantly: 1) can/cannot short-circuit, 2) 'xor' returns Perl's TRUE or FALSE i.e. 1 or 0/'', and 'or' returns differently (LEFT: evaluated expression; RIGHT: (evaluated?)expression with context propagation from outside). These operators look similarly (and, or, xor), but 'xor' behaves differently. Splitting needed for emphasis of difference.

(This is almost a copy of my suggestions which I wrote earlier to perlmonks https://perlmonks.org/?node_id=11128119)

I don't really see the need for splitting up the documentation as the OP requests. However, I do think we need better documentation of xor. Here is the sum total of our documentation of this operator:

Binary C<"xor"> returns the exclusive-OR of the two surrounding expressions.
It cannot short-circuit (of course).

This documentation assumes you already know what "exclusive-OR" means. If you do not, the Perl documentation is of no help; you have to go out on the internet and search for it. In twenty years of writing Perl, I encountered xor exactly once in real production code, so I would have to undertake that search as well.

Could someone suggest appropriate documentation for this section?

Thank you very much.
Jim Keenan

khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 4, 2025
khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 14, 2025
And, note that 'or' is "inclusive"; 'xor' is "exclusive"
And, explicitly give the results of bitwise '|' vs '^'
And, fix the incorrect use of 'binary' when 'logical' was meant.

Fixes Perl#18565
khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 17, 2025
khwilliamson added a commit to khwilliamson/perl5 that referenced this issue May 18, 2025
khwilliamson added a commit that referenced this issue May 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants