Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Ban “RHS” and “LHS” abbreviations
By removing them from words.pws and eliminating a few usages from the
docs.

We're sometimes criticized for using lingo that is unfamiliar to
beginners or those coming from other languages. While RHS and LHS are
fairly understandable abbreviations, I think we can just use
“right-hand side” or similar in most of the cases without sacrificing
anything.

I'm not entirely sure what would be the best way to hyphenate
it (right-hand side or right hand side? But not to be confused with
right-hand-side, right?). It would be nice if we were consistent about
it within our docs.
  • Loading branch information
AlexDaniel committed May 6, 2018
1 parent 39241d1 commit eb8f7f2
Show file tree
Hide file tree
Showing 14 changed files with 41 additions and 31 deletions.
2 changes: 1 addition & 1 deletion doc/Language/exceptions.pod6
Expand Up @@ -157,7 +157,7 @@ Output:
=end code
A C<try>-block is a normal block and as such treats its last statement as the
return value of itself. We can therefore use it as a RHS.
return value of itself. We can therefore use it as a right-hand-side.

This comment has been minimized.

Copy link
@JJ

JJ May 6, 2018

Contributor

You are using no dash between hand and side in the rest of the changes, right?

This comment has been minimized.

Copy link
@AlexDaniel

AlexDaniel May 6, 2018

Author Member

Yes… which is correct? I don't know, let's ask a native speaker.

This comment has been minimized.

Copy link
@JJ

JJ via email May 6, 2018

Contributor

This comment has been minimized.

Copy link
@dmaestro

dmaestro May 6, 2018

Contributor

right-hand side (no second dash) is more natural English. But a problem here is "right-hand side < of what?>". Should be clarified as "use it as a right-hand[-]side operand" or such? (most other example the context is more clear already.

  • right-hand is an adjective modifying "side"
  • "right-hand side of an assignment" when using RHS as a noun.
  • right-hand-side could also be an adjective, modifying something else: "right-hand-side operand".

This comment has been minimized.

Copy link
@dmaestro

dmaestro May 6, 2018

Contributor

Using in these cases as an adjective: https://www.merriam-webster.com/dictionary/right-hand

This comment has been minimized.

Copy link
@AlexDaniel

AlexDaniel Jun 22, 2018

Author Member

@dmaestro thank you! I created this ticket to continue the discussion: #2116

=begin code
say try { +"99999" } // "oh no";
Expand Down
8 changes: 4 additions & 4 deletions doc/Language/glossary.pod6
Expand Up @@ -604,9 +604,9 @@ object and also refers to the object itself.
=head1 lvalue
X<|Value>
An I<lvalue>, or a I<left value>, is anything that can appear on the left
hand side of the assignment operator C<=>. It is anything you can assign
to.
An I<lvalue>, or a I<left value>, is anything that can appear on the
left-hand side of the assignment operator C<=>. It is anything you
can assign to.
Typical lvalues are variables, private and C<is rw> attributes, lists of
variables and lvalue subroutines.
Expand Down Expand Up @@ -955,7 +955,7 @@ X<|rule>
=head1 rvalue
X<|rvalue>
A value that can be used on the right hand side of an assignment. See also
A value that can be used on the right-hand side of an assignment. See also
L<#lvalue>.
=head1 X<Semilist>
Expand Down
2 changes: 1 addition & 1 deletion doc/Language/list.pod6
Expand Up @@ -290,7 +290,7 @@ very context sensitive on a syntactical level.
=head2 List Assignment Context
When a list appears on the right hand side of an assignment into a C<@>-sigiled
When a list appears on the right-hand side of an assignment into a C<@>-sigiled
variable, it is "eagerly" evaluated. This means that a C<Seq> will be iterated
until it can produce no more elements. This is one of the places you do not want
to put an infinite list, lest your program hang and, eventually, run out of memory:
Expand Down
15 changes: 10 additions & 5 deletions doc/Language/operators.pod6
Expand Up @@ -147,7 +147,7 @@ or, if multiple matches were made, a L«C<List>|/type/List» of C<Match> objects
Returns C<$/>.
It's common to use this operator with the C<~~> smartmatch operator, as it
aliases left hand side to C<$_>, which C<s///> uses.
aliases left-hand side to C<$_>, which C<s///> uses.
Regex captures can be referenced in the replacement part; it takes the same
adverbs as the L«C<.subst> method|/routine/subst», which go between the C<s>
Expand Down Expand Up @@ -1215,7 +1215,7 @@ right function. If the L«C<.count>|/routine/count» of the left function is
greater than 1, the return value of the right function will be
L<slipped|/type/Slip> into the left function.
Both C<.count> and C<.arity> of the RHS will be maintained.
Both C<.count> and C<.arity> of the right-hand side will be maintained.
sub f($p){ say 'f'; $p / 2 }
sub g($p){ say 'g'; $p * 2 }
Expand Down Expand Up @@ -2233,11 +2233,16 @@ X<|...,operators>X<|...^,operators>X<|…,operators>X<|…^,operators>X<|lazy li
The X<sequence operator> will produce generic sequences on demand.
The left hand side will always include initial elements; it may include a generator too. The right hand side will have an endpoint, which can be C<Inf> or C<*> for "infinite" lists (whose elements are only produced on demand), an expression which will end the sequence when C<True>, or other elements such as L<Junctions>.
The left-hand side will always include initial elements; it may
include a generator too. The right-hand side will have an endpoint,
which can be C<Inf> or C<*> for "infinite" lists (whose elements are
only produced on demand), an expression which will end the sequence
when C<True>, or other elements such as L<Junctions>.
The sequence operator invokes the generator with as many arguments as
necessary. The arguments are taken from the initial elements and the already
generated elements. The default generator is C<*.>L<succ> or C<*.>L<pred>, depending on how the end points compare:
necessary. The arguments are taken from the initial elements and the
already generated elements. The default generator is C<*.>L<succ> or
C<*.>L<pred>, depending on how the end points compare:
say 1 ... 4; # OUTPUT: «(1 2 3 4)␤»
say 4 ... 1; # OUTPUT: «(4 3 2 1)␤»
Expand Down
4 changes: 3 additions & 1 deletion doc/Language/rb-nutshell.pod6
Expand Up @@ -456,7 +456,9 @@ puts "match 1!" if /bar/ === $foo; # Regex match
puts "match 2!" if $foo === "bar"; # String match
puts "match 3!" if String === $foo; # Class match
Please note that, in this case, C<===> is not symmetric; in the first and last case, the variable has to be in the right hand side. There is no equivalent to the signature class in Ruby, either.
Please note that, in this case, C<===> is not symmetric; in the first
and last case, the variable has to be in the right-hand side. There is
no equivalent to the signature class in Ruby, either.
See L<S03/Smart matching|https://design.perl6.org/S03.html#Smart_matching> for more information on this feature.
Expand Down
4 changes: 2 additions & 2 deletions doc/Language/regexes.pod6
Expand Up @@ -408,7 +408,7 @@ From example, to match C<dog> or C<dogs>, you can write:
=head2 X<General quantifier: C<** min..max>|regex quantifier,**>
To quantify an atom an arbitrary number of times, use C<**> quantifier.
The quantifier takes a single L<Int> or a L<Range> on the right hand side
The quantifier takes a single L<Int> or a L<Range> on the right-hand side
that specifies the number of times to match. If L<Range> is specified,
the end-points specify the minimum and maximum number of times to match.
Expand All @@ -422,7 +422,7 @@ the end-points specify the minimum and maximum number of times to match.
say 'abcdefg' ~~ /\w ** 1..*/; # OUTPUT: «「abcdefg」␤»
=end code
Only basic literal syntax for the right hand side of the quantifier
Only basic literal syntax for the right-hand side of the quantifier
is supported, to avoid ambiguities with other regex constructs. If you need
to use a more complex expression; for example, a L<Range> made from
variables—enclose the L<Range> into curly braces:
Expand Down
5 changes: 3 additions & 2 deletions doc/Language/syntax.pod6
Expand Up @@ -546,8 +546,9 @@ the next element is the value. Most often this is used with simple arrow pairs.
say %(a => 73, foo => "fish").keys.join(" "); # OUTPUT: «a foo␤»
# ^^^^^^^^^^^^^^^^^^^^^^^^^ Hash constructor
When assigning to a C<%> sigiled variable on the LHS, the sigil and parenthesis
surrounding the RHS C<Pairs> are optional.
When assigning to a C<%> sigiled variable on the left-hand side, the
sigil and parenthesis surrounding the right-hand side C<Pairs> are
optional.
my %ages = fred => 23, jean => 87, ann => 4;
Expand Down
10 changes: 6 additions & 4 deletions doc/Language/terms.pod6
Expand Up @@ -195,8 +195,9 @@ Variables are discussed in the L<variable language docs |/language/variables>.
X<|constant (Terms)>
Constants are declared with C<constant>, followed by an
L<identifier|/language/syntax#Identifiers> and do not require a sigil. The RHS
is evaluated at compile time, therefore being possibly too early to make sense.
L<identifier|/language/syntax#Identifiers> and do not require a
sigil. The right-hand side is evaluated at compile time, therefore
being possibly too early to make sense.
constant SpeedOfLight = 299792458; # m/s
Expand All @@ -205,8 +206,9 @@ is evaluated at compile time, therefore being possibly too early to make sense.
say POW2[16];
# OUTPUT: «65536␤»
Since constants RHS are evaluated at compile time, their usage within modules
could lead to unexpected behavior, please see the related
Since constant's right-hand side is evaluated at compile time, their
usage within modules could lead to unexpected behavior, please see the
related
L<traps section|https://docs.perl6.org/language/traps#Constants_are_Compile_Time>.
Constants are C<our>-scoped by default, but adding C<my> would make them lexical:
Expand Down
7 changes: 4 additions & 3 deletions doc/Language/traps.pod6
Expand Up @@ -530,7 +530,7 @@ and you can use C<:i> (C<:ignorecase>) adverb instead.
=head1 Pairs
=head2 Constants on the LHS of pair notation
=head2 Constants on the left-hand side of pair notation
Consider this code:
Expand Down Expand Up @@ -633,7 +633,8 @@ say join ", ", ("az", *.succ ... "bc");
=head2 Topicalizing Operators
The smart match operator C<~~> and C<andthen> set the topic C<$_> to their LHS.
The smart match operator C<~~> and C<andthen> set the topic C<$_> to
their left-hand-side.
In conjunction with implicit method calls on the topic this can lead to
surprising results.
Expand All @@ -657,7 +658,7 @@ say .&method ~~ 'topic';
=head2 Fat Arrow and Constants
The fat arrow operator C«=>» will turn words on its left hand side to C<Str>
The fat arrow operator C«=>» will turn words on its left-hand side to C<Str>
without checking the scope for constants or C<\>-sigiled variables. Use
explicit scoping to get what you mean.
Expand Down
4 changes: 2 additions & 2 deletions doc/Type/Baggy.pod6
Expand Up @@ -439,11 +439,11 @@ Defined as:
Used in smart-matching if the right-hand side is a C<Baggy>.
If the right hand side is the type object, i.e. C<Baggy>, the method
If the right-hand side is the type object, i.e. C<Baggy>, the method
returns C<True> if C<$other> L<does|/routine/does#class_Mu> C<Baggy>
otherwise C<False> is returned.
If the right hand side is a C<Baggy> object, C<True> is returned only if
If the right-hand side is a C<Baggy> object, C<True> is returned only if
C<$other> has the same elements, with the same weights, as the invocant.
my $breakfast = bag <eggs bacon>;
Expand Down
5 changes: 3 additions & 2 deletions doc/Type/Nil.pod6
Expand Up @@ -96,8 +96,9 @@ will result in an L<(Any)|/type/Any> type object.
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $y; expected Int but got Any (Any)␤»
If you are looking for a variable which transforms objects into type objects
when said variable appears on the RHS, you can type the container as C<Nil>.
If you are looking for a variable which transforms objects into type
objects when said variable appears on the right-hand side, you can
type the container as C<Nil>.
my Nil $x;
my Str $s = $x;
Expand Down
2 changes: 1 addition & 1 deletion doc/Type/Signature.pod6
Expand Up @@ -244,7 +244,7 @@ type objects. To do this, we can use the C<:D> type constraint. This constraint
checks that the value passed is an I<object instance>, in a similar fashion to calling
its L<DEFINITE|/language/mop#DEFINITE> method.
To warm up, let's apply C<:D> to the right hand side of our humble C<Int> example:
To warm up, let's apply C<:D> to the right-hand side of our humble C<Int> example:
say 42 ~~ Int:D; # OUTPUT: «True␤»
say Int ~~ Int:D; # OUTPUT: «False␤»
Expand Down
2 changes: 1 addition & 1 deletion doc/Type/Whatever.pod6
Expand Up @@ -82,7 +82,7 @@ my $series = known-lower-limit() ... $max;
A stored C<*> will also result in the generation of a C<WhateverCode> in the specific
case of smart match. Note that this is not actually the stored C<*> which is being curried, but
rather the C<*> on the LHS.
rather the C<*> on the left-hand side.
=for code :preamble<sub find-constraint {};>
my $constraint = find-constraint() // *;
Expand Down
2 changes: 0 additions & 2 deletions xt/words.pws
Expand Up @@ -583,7 +583,6 @@ lexpad
lf
lgtm
lhf
lhs
libmysqlclient
libname
libs
Expand Down Expand Up @@ -972,7 +971,6 @@ rethrows
reusability
rewinddir
rfc
rhs
rindex
rlwrap
rmdir
Expand Down

0 comments on commit eb8f7f2

Please sign in to comment.