DEV Community: Brandon Weaver

Ruby in FantasyLand: SumsUp

Brandon Weaver — Tue, 24 May 2022 06:05:56 +0000

Javascript comes with this lovely little spec called Fantasy Land that defines certain type classes in Category Theory and how they interact.

Years ago, when I was particularly interested in learning about Category Theory, Algebraic Types, and the lot of it I had stumbled upon a lovely series from Tom Harding called Fantas, Eel, and Specification which I got quite a bit of enjoyment from.

This series, with the permission of Tom, is a reinterpretation of those posts in Ruby along with some of my own thoughts.

With that said, let's get into it.

SumsUp

The initial post that we're working from is the introduction into both data classes and sum types using Daggy, and you can read the original post here:

http://www.tomharding.me/2017/03/03/fantas-eel-and-specification/

Now with Ruby we have a few different ideas we want to express. Whereas Daggy has tagged and taggedSum we have Struct and SumsUp.define instead. You can find more info on SumsUp here, but we'll be covering the general details in this post.

Struct vs Tagged

The idea of Daggy's tagged method is to create a succinct inline type. In Ruby we have Struct which matches this use case, which you can compare:

//- A coordinate in 3D space.
//+ Coord :: (Int, Int, Int) -> Coord
const Coord = daggy.tagged('Coord', ['x', 'y', 'z'])

//- A line between two coordinates.
//+ Line :: (Coord, Coord) -> Line
const Line = daggy.tagged('Line', ['from', 'to'])

To the Ruby equivalent:

Coord = Struct.new(:x, :y, :z)
Line = Struct.new(:from, :to)

If we really wanted to be precise we could even look into Sorbet Typed Structs for the sake of explicitness:

require "sorbet-runtime"

class Coord < T::Struct
  extend T::Sig

  prop :x, Integer
  prop :y, Integer
  prop :z, Integer

  sig { params(x: Integer, y: Integer, z: Integer).returns(Coord) }
  def translate(x:, y:, z:)
    Coord.new(x: @x + x, y: @y + y, z: @z + z)
  end
end

class Line < T::Struct
  prop :from, Coord
  prop :to, Coord
end

a = Coord.new(x: 1, y: 2, z: 3)
b = Coord.new(x: 0, y: 2, z: 3)

path = Line.new(from: a, to: b)

Coord.new(x: 1, y: 2, z: 3).translate(x: 1, y: 1, z: 1)
# => <Coord x=2, y=3, z=4>

...but that may be a matter for a later day, and an exercise left to the reader, though I would still recommend explicit classes if you find yourself writing methods on data objects like this.

Anyways, that aside, we also need to know how to put basic methods on a Struct as well, and there are two ways to do that:

Coord = Struct.new(:x, :y, :z) do
  def translate(x, y, z)
    self.class.new(self.x + x, self.y + y, self.z + z)
  end
end

Coord.new(1, 2, 3).translate(1, 1, 1)
# => #<struct Coord x=2, y=3, z=4>

Coord.define_method(:move_north) do |y = 1|
  self.class.new(self.x, self.y + y, self.z)
end

Coord.new(1, 2, 3).move_north(2)
# => #<struct Coord x=1, y=4, z=3>

Though honestly by that rate I would likely consider creating a class instead as this can get a bit complicated.

Oh, and you can do this with Struct, same as new:

Coord[1, 2, 3]
# => #<struct Coord x=1, y=2, z=3>

As another aside I tend to prefer keyword_init as it makes things clearer:

Coord = Struct.new(:x, :y, :z, keyword_init: true)
Coord.new(x: 1, y: 2, z: 3)
# => #<struct Coord x=1, y=2, z=3>

The intention of tagged and Struct are to give a name to a piece of data, and then give names to the fields or properties in that data, making them a handy quick utility for simpler cases. If you find yourself going beyond the simple, however, perhaps a class will make more sense.

taggedSum vs SumsUp define

Now this one will be a bit more foreign. Starting with the example provided, Bool, which can be true or false. That means a type with multiple constructors, or a "sum" type:

const Bool = daggy.taggedSum('Bool', {
  True: [], False: []
})

...and in Ruby:

Bool = SumsUp.define(:true, :false)

As neither have arguments the define method accepts a list of variants without arguments. Where this gets more interesting is around ones that do:

const Shape = daggy.taggedSum('Shape', {
  // Square :: (Coord, Coord) -> Shape
  Square: ['topleft', 'bottomright'],

  // Circle :: (Coord, Number) -> Shape
  Circle: ['centre', 'radius']
})

...and in Ruby:

Shape = SumsUp.define(
  # Square :: (Coord, Coord) -> Shape
  square: ["top_left", "bottom_right"],

  # Circle :: (Coord, Number) -> Shape
  circle: ["center", "radius"]
)

This gives us something quite foreign to work with, as now we're not working with inheritance but rather describing the shapes of data and how we interact with them:

Shape.prototype.translate =
  function (x, y, z) {
    return this.cata({
      Square: (topleft, bottomright) =>
        Shape.Square(
          topleft.translate(x, y, z),
          bottomright.translate(x, y, z)
        ),

      Circle: (centre, radius) =>
        Shape.Circle(
          centre.translate(x, y, z),
          radius
        )
    })
  }

Shape.Square(Coord(2, 2, 0), Coord(3, 3, 0))
    .translate(3, 3, 3)
// Square(Coord(5, 5, 3), Coord(6, 6, 3))

Shape.Circle(Coord(1, 2, 3), 8)
    .translate(6, 5, 4)
// Circle(Coord(7, 7, 7), 8)

...and in Ruby this would be:

Coord = Struct.new(:x, :y, :z) do
  def translate(x, y, z)
    self.class.new(self.x + x, self.y + y, self.z + z)
  end
end

Shape = SumsUp.define(
  # Square :: (Coord, Coord) -> Shape
  square: [:top_left, :bottom_right],

  # Circle :: (Coord, Number) -> Shape
  circle: [:center, :radius]
) do
  def translate(x, y, z)
    match do |m|
      m.square do |top_left, bottom_right|
        Shape.square(
          top_left.translate(x, y, z),
          bottom_right.translate(x, y, z)
        )
      end

      m.circle do |center, radius|
        Shape.circle(center.translate(x, y, z), radius)
      end
    end
  end
end

Shape
    .square(Coord[2, 2, 0], Coord[3, 3, 0])
    .translate(1, 1, 1)
# => #<variant Shape::Square
#     top_left=#<struct Coord x=3, y=3, z=1>,
#   bottom_right=#<struct Coord x=4, y=4, z=1>
# >

Shape.circle(Coord[1, 2, 3], 8).translate(6, 5, 4)
# => #<variant Shape::Circle
#   center=#<struct Coord x=7, y=7, z=7>,
#   radius=8
# >

Note: As types stack up here though I do become more convinced that Sorbet may be a good addition to the following parts of this tutorial, and may see about working around SumsUp or make a similar interface later. Feedback welcome.

Now the tutorial mentions Catamorphisms, as Daggy uses cata, but to me this is very similar to pattern matching of which SumsUp provides their own interface for. There may be an additional case for introducing pattern matching from Ruby 2.7+ into these interfaces later, but I digress again.

The original article sums (ha) it up nicely by saying that sum types are types with multiple constructors.

Lists with Sums

Now let's take a look at the final example mentioned here:

const List = daggy.taggedSum('List', {
  Cons: ['head', 'tail'], Nil: []
})

List.prototype.map = function (f) {
  return this.cata({
    Cons: (head, tail) => List.Cons(
      f(head), tail.map(f)
    ),

    Nil: () => List.Nil
  })
}

// A "static" method for convenience.
List.from = function (xs) {
  return xs.reduceRight(
    (acc, x) => List.Cons(x, acc),
    List.Nil
  )
}

// And a conversion back for convenience!
List.prototype.toArray = function () {
  return this.cata({
    Cons: (x, acc) => [
      x, ... acc.toArray()
    ],

    Nil: () => []
  })
}

// [3, 4, 5]
console.log(
  List.from([1, 2, 3])
  .map(x => x + 2)
  .toArray())

...and the Ruby variant:

List = SumsUp.define(cons: [:head, :tail], nil: []) do
  def map(&fn)
    match do |m|
      m.cons do |head, tail|
        List.cons(fn.call(head), tail.map(&fn))
      end

      m.nil {}
    end
  end

  def to_a
    match do |m|
      m.cons { |head, tail| [head, *tail.to_a] }
      m.nil {}
    end
  end

  def self.from(plain_list)
    # Approximation of "reduce_right"
    plain_list.reverse.reduce(List.nil) do |acc, v|
      List.cons(v, acc)
    end
  end
end

List.from([1, 2, 3])
# <variant List::Cons head=1, tail=
#   <variant List::Cons head=2, tail=
#     <variant List::Cons head=3, tail=#<variant List::Nil>>>>

List.from([1, 2, 3]).map { |x| x + 2 }
# <variant List::Cons head=3, tail=
#   <variant List::Cons head=4, tail=
#     <variant List::Cons head=5, tail=#<variant List::Nil>>>>

List.from([1, 2, 3]).map { |x| x + 2 }.to_a
# => [3, 4, 5]

Which gives us an interesting brief look into linked lists and some old lisp naming with cons, though others might recognize car and car more readily.

Wrap Up

That about wraps us up on the first post. You can find the rest of Tom Harding's lovely series here if you want spoilers, otherwise it may be prudent to convince me on Twitter not to try and hack together an algebraic datatype library with Sorbet-aware classes as I find myself quite tempted at the moment.

The next post goes into type signatures, and from there we start a very interesting journey. While you may recognize some patterns and have your own intuition around them (cata/pattern matching looks like inheritance) keep an open mind for the moment and see where it takes us from here.

Oh, and yes, this is a Monad tutorial in the end.

Tales of the Autistic Developer – The Politician

Brandon Weaver — Mon, 21 Mar 2022 00:08:20 +0000

For those who don't know me, I'm autistic. I've been a developer for the better part of a decade.

I didn't find out I was ASD until 19, and didn't reconcile with that until years later. These posts will be a combination of advice I've given to those who are like me, as well as a letter of sorts to my past self who could have used a lot of it.

I write these posts in the hopes that someone like me will find value in knowing a very simple and very important truth about ASD:

You are not alone, and you are loved.

The Politician

If you were to ask any number of engineers what their most dreaded part of the job is it would not be surprising to see many answer politics. Bureaucracy, roadblocks, arguments everywhere, and all seemingly for no good reason other than to make things slow.

Yet politics are perhaps the most important part of a software engineers job.

Now autistic folks, we're not known for our social graces and understanding of fine nuance. If politics are such an integral part of the job it seems counterintuitive if not impossible that someone that's autistic has found any reasonable success there.

That, dear friends, is precisely what this post is going to address.

Defining the Term

To start: when I say politics what exactly do I mean? How do we define that for the sake of this article?

We will be taking a very narrow focus on corporate politics at scale, and how they relate to team dynamics in a company at varying levels.

We will not be addressing global politics and how that relates to corporate, as that's deserving of a much longer post with far more nuance and attention than I'm capable of giving it at the moment. Sufficient to say this type is exceptionally important, and companies that pretend otherwise do so to their folly.

The New Politician - Local Scope

When you're new to a job your focus is exceptionally localized and the politics you tend to be exposed to are likewise exceptionally localized. When I was at this level I saw a problem and I solved it, simple as that. Whenever someone stopped me from doing so or changed my trajectory I would scowl off and complain about politics, rather than take time to understand what was really going on.

The Problem

This led to a lot of problems, as I would very frequently feel betrayed or otherwise ignored whenever my work would dramatically shift, assuming that those above me didn't get it. When I felt this I would start raising arguments and advocate very harshly for what I believed should be done.

I would broker no discussion, and fail to listen, because in my mind I knew what needed to be done and others just didn't get it yet. Because of how fixated I became on localized problems I missed the much wider picture of the business value the team was meant to deliver, and the strategic direction of my leadership.

Likewise I did not want to be involved in all of these meetings about planning, backlog grooming, quarterly roadmapping, or other strategic meetings. I'd found them to be a massive waste of time when we could just work on what was in front of us and the very obvious problems as I saw them.

The Solution

A recurring theme throughout my posts, and one thing that I want to repeat as many times as necessary:

Listen, then listen more, then make absolutely sure you've heard and listened again before opining.

I had to start to learn what the wider picture was of the team and where they were headed, and how my work fit into that picture. Once I started to see that picture it made a lot more sense why work I had thought was important did not get prioritized, and why it seemed that I was constantly thrashing in my job instead of getting things done.

The Strength

Perhaps ironically my stubbornness and insistence on seeing something through led to a very unusual strength that's been commented on even up to today: tenacity.

If I truly believe something is an issue I fully intend to pursue it and make sure it's fixed.

When I learned to start listening I learned which issues were actually issues, and which ones were me not understanding the situation. It also taught me how to frame issues so that they would be prioritized by aligning myself with management and leads to show why it should be valued over other tasks.

It was also the start of me seeing business value in what I did and how that translated into my teams deliverables.

The Experienced Politician - Team Scope

Once you've had a few years to mature as an engineer, and before you get to senior, you fall into one of the most dangerous parts of your career. It's a valley where one can presume expertise and knowledge where it isn't, and because of that you foster exceptionally strong opinions. Any of the strengths from the last section can become exceptional weaknesses if leveraged wrongly.

The Problem

The buried lede in the previous strength section is whether I truly believed something to be an issue. Given how self-righteous I was in the past you can imagine this was a very very bad idea as it would lead me to advocating exceptionally strongly for things that weren't really issues.

Even worse, now I had enough sense to frame the case in such a way that I could potentially get the work roadmapped whether or not it made sense.

I say this is a dangerous period as you have just enough experience to make a case, but not enough maturity to do so wisely yet. We mistake knowledge for wisdom, and with it the discretion that should be there to prevent self-righteous crusades and tilting at windmills.

The Solution

Remember the solution to the last section? Listening. It's a lesson that bears repeating daily if not hourly or minutely, perhaps even more frequently. The higher level you become the more fatal it is not to listen and go along with creating your own solutions without input from others.

This was the stage of my career where I begun to form networks of friends, coworkers, organizational teammates, and company experts. Through them I could check myself to make sure what I was doing made sense, vet ideas, and qualify if this was something that was truly an issue or if I was just particularly worked up that day.

It forced a reliance on my team, rather than acting out as an individual apart from them, even though leveling scope would have you believe self-sufficiency is the ultimate goal.

The Strength

Perhaps my greatest strength as an engineer is my network. I'm one person, there's no possible way I have all the context required to make decisions, and the higher leveled I became the more critical this skill became. In later sections I'll highlight how this grew, but for now this was the start of me building and working through my network, albeit at a minimal scope at this moment.

The Senior Politician - Team to Organization Scope

After you get beyond the brick wall before senior levels you'll find still more hurdles to overcome. This is the level where representation matters, delegation enters the conversation, and cross-team planning becomes a requirement to get progressively larger tasks done.

The Problem

By now I had cooled my head, learned to listen to others, but I had a whole new level of problem to contend with: I had to convince other people that something was a good idea to pursue.

More often than not I would do so by informal conversations, convincing people to help with work outside of the scope of their teams roadmaps if not completely aside from it. I would try and circumvent the chain of command at a company for expediency on projects I happened to think were important.

Needless to say this did not endear me to people outside of my team and organization as I represented a risk factor that could derail their roadmap by not considering the implications of the work I was trying to get people to do.

The Solution

Process, surprisingly, exists for a very good reason. That meant getting things roadmapped for other teams and learning negotiation skills when consulting with other team leads and managers, rather than taking advantage of engineers who didn't happen to know any better. Granted there's another message in there about volunteer culture and how that can dramatically backfire, but we'll get into that in a moment.

No, for this section the growth areas were around learning to negotiate and get things on a roadmap, schedule the work, and then see it through rather than tossing something over the fence and hoping it magically showed up done on the other side.

It meant having uncomfortable discussions and accepting when the answer was sometimes no, and working with that to reprioritize or in rare cases escalating to surface truly severe concerns. Sometimes, even then, the answer is still no and I had to learn how to work with that.

The Strength

Through this I had learned how to start negotiations, how to prepare formal documents and proposals, and how to make effective cases for what I believed should be done which led to a much higher rate of success and delivery.

In some ways one could fairly say "give us a proposal" is code for "screw off, we're busy" and they may be right there, though I choose to take a sunnier view of that and say it's more likely to mean they need a full story of the scope of the request and the details behind it beyond a simple "X is a problem, we should fix that."

It taught me to solidify context and details of problems into actionable items that could be delivered to others, rather than requiring my direct involvement to get things done. It was the start of me learning to delegate and break apart work, which is what got me to Staff levels.

The Staff Politician - Organization to Company Scope

Beyond Senior levels there's a much higher wall to climb to Staff levels, and that's because the lesson here is that it's no longer an individual contributor's job, it's a leader's job to work through an entire organization rather than trying to play solo hero any more.

It's a hard lesson to learn, and I was no exception.

The Problem

You spend years building engineering intuition on how to solve a problem yourself. You could totally get it done in a few hours if they'd let you, they just don't understand how simple it actually is, they're overcomplicating things!

Sufficient to say I was still fairly arrogant at this stage of my career. I believed I could solo tasks that were well beyond the realm of what any single engineer should ever attempt on their own. Not because I couldn't, no, but because I shouldn't.

The Solution

Shouldn't is a real loaded word there. What do I mean by that?

If a problem is beyond the scope of a single engineer and can effect a whole organization and even the entire company there's no possible way that engineer has enough context to fully realize and deliver on that problem. To think otherwise is folly, and likely to lead to a lot of misses in delivery for not really understanding a domain and customer requirements.

The solution, again, was listening and on a much grander scale. It meant having several meetings, message chains, documents, proposals, and more to make sure a domain was fully explored and qualified rather than making assumptions that could lead to failure.

It meant no longer being an engineer, but being a representative for an entire organization of engineers that trust you to make wise decisions. Sometimes this can even reach a company scale at this level.

It means that all the negotiation skills developed up to this point are now table stakes for any reasonably sized job.

The Strength

Through this I had also learned a critical skill that I had not quite realized. Delegating at that scale means that you can grow engineers effectively. It means that you can ensure people are connected that can help each other grow, that you can give tasks that address weaknesses, and that you can create examples of competencies that can be leveraged in promotions.

At this stage I started to realize the ability to level up an entire organization around me, and start to establish networks of experts not only in the company, but in the entire industry.

It was the beginning of me starting to actually lead, and hopefully do so wisely as a representative of both my team and organization.

The Principal Politician - Company to Industry Scope

After all of this I find myself at a new stage, that of a Principal Engineer, that is still beyond my full understanding. Really Staff in many cases may still be.

At this level any decision you make can rock an entire company, if not the entire industry around you, and because of that it requires exceptional wisdom, patience, and listening to succeed in.

Unfortunately I only have two of those on a good day, and which two those are depends on the problem at hand.

The Problem

By now you're not only a representative for your organization, but for the entire company if not the entire industry. To say that that requires a deft and steady hand is an exceptional understatement.

The cost of failure becomes exceptionally high, even terrifying to the point of stagnation and avoidance of unfamiliar territory. It can mean becoming stuck in your ways and refusing to change, returning and harkening to some of the arrogance from previous stages.

The problem now is that you have enough experience to back that up, and using it irresponsibly can do immeasurable damage to a company and its engineers. Being the representative of an entire company is a significant responsibility.

The Solution

Fail. Fail often, fail fast, and be willing to make mistakes.

Of course this sounds patently absurd, who would recommend failing as a solution?

The trick here is to fail in such a way that you've made it cheap, easy, and fast to recover and shift positions. It allows you to take much larger risks safely and qualify risks that may otherwise be unknown through formal proposal and discussion.

Even the best decisions and most well thought out proposals will inevitably have failure modes. It's impossible to get everything right, so optimizing for such can be foolish and costly, as it presumes a perfection which will never exist.

Amusingly even if you could get something perfect it would still be wrong because software is by nature a moving target. Demands change, needs shift, customers cycle, and no one person can reliably predict the future. Through maturity though they can certainly make some educated guesses.

The Strength

By being willing to fail and consider the risks taken one starts to develop skills of tactical investments and being able to delegate entire organizations to pursue promising potentials and qualify whether or not they pan out.

It develops a far more robust model of software where teams are safe to make mistakes, to grow and learn at a much larger scale, and start to produce more Staff level competencies and perhaps beyond. When failure is untethered from shame it allows for growth and transparency at a company scale, and a much healthier engineering culture will emerge from it.

In conjunction with the other strengths an engineer executing at this level can do some incredible things.

Truthfully these are still lessons I am learning, and will continue to learn over the next few years as I mature into this level myself.

Closing Thoughts

Politics take different shapes at every stage, but the truth of the matter is that there needs to be a healthy relationship with expectations at every level for there to be safety to grow in them. Some companies naturally will be exceptionally hostile here with top-down mandates while others will have no structure and let people do as they will. Both have their failure modes and create very different political climates to work in.

In many ways I am still ever much the fool in regards to political nuance at work, but I have certainly grown from where I was in the past, and can see ways I can continue to improve myself in the future.

One step at a time, we grow every day, and you're just as capable of that growth yourself.

So go out, experiment, fail, and above all?

LISTEN

Tales of the Autistic Developer – Order and Chaos

Brandon Weaver — Fri, 19 Nov 2021 10:05:15 +0000

For those who don't know me, I'm autistic. I've been a developer for the better part of a decade.

I write these posts in the hopes that someone like me will find value in knowing a very simple and very important truth about ASD:

You are not alone, and you are loved.

Order and Chaos

While I am most certainly autistic, I'm also ADHD, making for a very interesting mix of traits. My mind, quite simply, operates in a mode of constant chaos.

It bounces from idea to idea as fast as something catches its fancy, and trying to tame it into some semblance of productivity has been my life's work.

The irony then is that my entire existence is implementing systems of order by which to counteract that natural state of chaos, but the deeper irony? Both have become indispensable to my work, and how I think.

A State of Chaos

In my decade or more of experience in the industry I've come to a very simple truth:

The hardest problems in technology are organizational, rather than technological.

While solutions may certainly exist, discovering them, building consensus, and orchestrating the release ends up being an exercise in chaos more often than not. There are entire categories of problems that are well beyond the scope of a single engineer, and quite frankly should be despite the best efforts of some to do otherwise.

The larger the problem the larger the surrounding context it involves, and by extension the more people will need to be involved to solve it properly. Bypassing this means bypassing critical context and insight, and potentially making very grave mistakes in the solutions you create.

Simply put that's the critical gap between a Senior and a Staff engineer, but that's a story for another day.

The point of this is that without a plan and systems of communication, organization, networking, and other methods of managing all that context you end up with chaos. A ship without a rudder sailing aimlessly into the distance.

That might work well for the short term, but direction becomes critical if you want to do anything beyond floating in a loosely forward direction.

Now this all brings up a very interesting question: how does someone with Autism / ADHD, both conditions known for not being great at all of the above, manage to survive past those levels?

A Contradictory Existence

As someone with Autism I like things to make sense, to have a natural order, and to fall into the right place. My life is dominated in many ways by a desire for order and rigor. Take me to any restaurant and I guarantee I'll order the same thing every time, and most of the owners will know me by name if I've lived somewhere for any decent amount of time. Consistency brings me peace of mind, and helps me to focus.

You can imagine that 2020 and 2021 were not kind on that note, but again, a story for another day.

Contradictorily and very ironically being ADHD means that my mind works in a state of disorder. I bounce between 10 ideas at any given time, find new hobbies everywhere, and can't focus to save my life.

These two traits are at constant odds with each other in my head. In many cases it feels like I humor myself between the two of them depending on which trait dominates on a given day. Do I need to snap out of an obsession from my Autistic nature, or do I need to drill down and focus on one task and quit being capricious from my ADHD nature?

Systems of Order

The answer is that I use them both against each other, where one is weak I supplement the other's strength. I create systems of order in which I can succeed with ADHD, via calendars, notes, reminders, and anything else I can get a hold of to keep myself accountable.

I have collections of notes spanning many years capturing insights, networks, communications, and more to make sure I can find the right people when I need to to get critical context. I create systems by which to capture and distill that information into useful documents, and further methods to distill that information into actionable content and executive summaries to inform those above me on a path forward.

The simple truth is I do not trust myself to be responsible, so any system of order I make is explicitly to keep myself accountable to a task. Being autistic I find great comfort in order and certainty, in rote and repetition of tasks, which means I'm very good at creating order of chaos.

What's interesting about that statement is the reverse: To get good at creating order of chaos, one has to be able to live in chaos and thrive in it first. ADHD's lack of a clear focal point and its tendency for capriciousness benefits me in that I'm far more comfortable with disorder and chaos than many without it. After all, my head works like that, even if I do like order more.

The critical point is that I can recognize chaos for what it is, and in doing so start to implement systems of order on top of it to facilitate progress. The larger the chaos the more this ability shines, but there are certainly dangers in forms of chaos that I cannot comprehend nor manage, so knowing my limit is critical in stepping back and consulting others first.

What's more interesting is that these systems of order allow something else entirely.

The Cost of Freedom

Through systems of order balancing chaos, I'm allowed a certain freedom of execution. I've created a solid foundation in which I can experiment, do as I will, and explore beyond scopes I may have been able to more early in my career.

When I was much younger I did not have such systems of order, yet I yearned for freedom. Freedom to play, to explore, to do what I wanted to do. Many times, when given such freedom, it would be my undoing. If anything seeking freedom was what about got me fired in a few roles in the past, as I did not have nearly the support structure I needed to execute upon it.

By creating systems of order that can sustain me, and networks by which I can execute through, I'm able to create greater freedoms by which myself and others can pursue tasks as we wish.

The irony, and the cost of that freedom, are systems of organization to prevent chaos beyond our ability to manage from eroding our foundation and putting us in positions where tasks are quite literally impossible to achieve.

I know, I've put myself in that position several times before, and it's not fun.

That said, it was probably those very experiences that gave me the critical insight that there's a high cost to freedom, and the higher one goes and the wider scope that one executes at that cost grows with it.

Consider a manager who creates systems of organization through Jira or Agile methodologies (it could be anything though, those are just examples). Through that newer engineers can execute tasks to move the team forward, but inside that framework they have the freedom to add tasks and propose new solutions, all because the team is still moving forward due to the manager's planning.

That manager shields the team from chaos beyond their scope of view, and in doing so gives them the freedom to execute in their own scope. Of course as team members level up they'll become privy to far more of the chaos the team is wrapped up in, but preferably only when they're ready to face it.

Extrapolate this to directors, department heads, GMs, VPs, C-levels, and more and you can see that the costs of organizing at each progressive level grow exponentially, but the freedom and clarity they provide by doing so to those under them grows with it.

That's a pretty amazing power, and one I hope to have one day, but one I have a lot of work to do to get to.

Superpower or Curse?

I exist in a world somewhere between chaos and order, creating order of chaos, and living a life that allows me to survive chaos perhaps beyond what would otherwise be normal. While this may sound like some form of superpower, it's far more a precarious balancing act, and if I happen to slip and let one side dominate it does not end well for me.

Should I let my Autistic nature dominate, I'll begin to lock down and go back to the familiar. Anything outside of that box won't happen, and I'll likely be like that for a week or two while I regain my composure. I start to jettison anything and everything not necessary to finish existing commitments, and will very much be in a state of Autistic burnout. Recovery from that is painful, and frequently I try and take a vacation when I find myself flirting too much with that line.

Should I let my ADHD nature dominate I'll get nothing done. I'll be on an endorphin hunt looking for anything and everything that can give me just a bit of a rush. Whether that be shopping, smells, foods, experiences, new comics, books, games, or any of the above I want something to make me feel whole and "happy" again, despite that being impossible. ADHD burnout means that I'll be on a perpetual hunt for a new high, until I detox my mind and get back to a normal state.

If you know me personally you'll notice that I have routines, whether that be coffee or food, that I tend to adhere to to satisfy my Autistic nature. You'll also notice the tendency of me pursuing new and novel hobbies on occasion, but in very limited quantities, to satisfy my ADHD nature.

I can't ignore them, but neither can I let them win and dominate my life, which brings up the question if this is a superpower or a curse.

Really though? It depends on the day.

Closing Thoughts

As I grow in my career my permanent fear is that I encounter chaos beyond my capacity requiring order that tips me beyond my limits. Thankfully I've had the support of many wise friends, mentors, elders, and family to guide me through those times. People who have been there, and seen the tops of the mountains I'm climbing, and that's made all the difference in the world. To even know it's possible, and that my ideals aren't wrong, is more valuable than gold to me.

If there's one final lesson I could impart from this article it's that you're not in this alone, not now and not ever. There will be things beyond us, but there will also be people there with an outstretched hand if you look for them.

We are not alone, not in the greatest chaos, nor in the most thorough systems of order we could imagine. Alone we will fail, but together we can achieve so much more, and that's a lesson I wish I had learned much earlier in my life.

Future of Ruby – AST Tooling

Brandon Weaver — Sun, 14 Nov 2021 08:22:39 +0000

This is a series meant to explore the potential future of the Ruby programming language by visiting current technologies and ideas around them, and how those might apply to the future. In this series you'll find some tools which can be used today, some which may be used tomorrow, and a collection of aspirations of what could be.

As this is a look into a potential future, you may or may not see these things come to pass, and that's ok. This is not meant to be prescriptive, but to start conversations on what things could be.

With that being said, let's take a look into the potential future of Ruby.

AST Tooling

Programs are, at their core, text with special semantic meaning. Using Regex we can certainly treat Ruby as just plain text, but in doing so we lose the semantic meaning of what makes Ruby Ruby.

Enter in ASTs, or Abstract Syntax Trees. ASTs are a data structure that represents a Ruby program as a series of nested nodes, broken into relevant pieces using knowledge of the language.

Ruby has a few different implementations of this, the core implementation being Ripper:

pp Ripper.sexp('def hello(world) "Hello, #{world}!"; end')
# [:program,
#   [[:def,
#     [:@ident, "hello", [1, 4]],
#     [:paren,
#      [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]],
#     [:bodystmt,
#      [[:string_literal,
#        [:string_content,
#         [:@tstring_content, "Hello, ", [1, 18]],
#         [:string_embexpr, [[:var_ref, [:@ident, "world", [1, 27]]]]],
#         [:@tstring_content, "!", [1, 33]]]]],
#      nil,
#      nil,
#      nil]]]]

The AST is represented as a series of nested arrays. The problem with this, of course, is that it can be difficult to work on programmatically for tooling developers.

Enter the Whitequark parser, which you can experiment with here:

ruby_code  = 'def hello(world) "Hello, #{world}!"; end'
expression = Parser::CurrentRuby.parse(ruby_code)
# s(:def, :hello,
#   s(:args,
#     s(:arg, :world)),
#   s(:dstr,
#     s(:str, "Hello, "),
#     s(:begin,
#       s(:lvar, :world)),
#     s(:str, "!")))

There are a few others like Melbourne, JRubyParser, and ruby_parser but we'll focus on the Whitequark parser for the sake of this article.

Put simply, I believe that it's more accessible and easily usable than Ripper, and will be the base of a lot of what could be the future of Ruby tooling. That's what we're going to explore today.

We'll be covering the following topics:

Find and Replace - Regex and literal F&R is limited and prone to accidental replacements. Can we be more precise?
EmberJS Style Codemods - EmberJS uses Codemods to upgrade itself, and ships with them every major version. Think that, but Rails or other major Ruby gems.
Babel Transpilation - JS evolves so quickly because you can fairly easily try out experimental syntax via Babel and get proofs-of-concept out fast.
A to B Inferred Transforms - Given code "A" find the transformations necessary to get to code "B".
Macros - The Whitequark parser has a dual, Unparser. If Parser was standard Ruby, and any live code could be turned into an AST, we could rearrange it for some dramatic effects.

Now that's a lot of ground to cover, so shall we get started?

Find and Replace

Let's say you wanted to replace every instance of a certain piece of text in your program with another one. Most editors have a find and replace function with added regex support which can be very handy.

For this example let's say you decided that you had named a variable hash and want to replace it with something more descriptive, such as person:

hash = HTTP.get('some_site/people/1.json').then { JSON.parse(_1) }
puts "#{hash['name']} was found!"

Sure, it'd work for this case, but say that right below that code was something like this:

puts "#{test_object.name} is currently #{test_object.hash}"

A global find and replace would be a real bad idea in this case, changing the meaning of your program. This is because the text "hash" has no semantic meaning, but a node related to "hash" definitely does:

# HEREDOCs surrounded in single-quotes prevents interpolation, which
# we need here.
Parser::CurrentRuby.parse <<~'RUBY'
  hash = HTTP.get('some_site/people/1.json').then { JSON.parse(_1) }
  puts "#{hash['name']} was found!"
  puts "#{test_object.name} is currently #{test_object.hash}"
RUBY

# This generates the following AST:
s(:begin,
  s(:lvasgn, :hash,
    s(:numblock,
      s(:send,
        s(:send,
          s(:const, nil, :HTTP), :get,
          s(:str, "some_site/people/1.json")), :then), 1,
      s(:send,
        s(:const, nil, :JSON), :parse,
        s(:lvar, :_1)))),
  s(:send, nil, :puts,
    s(:dstr,
      s(:begin,
        s(:send,
          s(:lvar, :hash), :[],
          s(:str, "name"))),
      s(:str, " was found!"))),
  s(:send, nil, :puts,
    s(:dstr,
      s(:begin,
        s(:send,
          s(:send, nil, :test_object), :name)),
      s(:str, " is currently "),
      s(:begin,
        s(:send,
          s(:send, nil, :test_object), :hash)))))

Now we have hash referring to a node of type :lvasgn (local variable assign) and :lvar (local variable) as opposed to the later node s(:send, s(:send, nil, :test_object), :hash))) which relates to the hash method being called on the test_object.

ASTs gave distinct meaning to each part of that text, and given that we could more easily do replacements in a much more descriptive way. Think of it, in a way, like static typing for manipulating a program and ensuring your intent is more clearly expressed and executed.

Editors currently have regex support, but who's to say that we couldn't have AST or NodePattern support in the future?

Using MarcAndre's NodePattern tool we can even use a regular language designed for ASTs known as NodePattern to find any local variable or assignment related to hash (borrowing some from src):

require "rubocop"
require "parser/current"

def ruby_parser
  builder = ::RuboCop::AST::Builder.new
  parser = ::Parser::CurrentRuby.new(builder)
  parser.diagnostics.all_errors_are_fatal = true
  parser
end

def ast_of(s)
  buffer = ::Parser::Source::Buffer.new('(ruby)', source: s)
  ruby_parser.parse(buffer)
end

def node_pattern(s) = RuboCop::NodePattern.new(s)

hash_match = node_pattern <<~NODE
  { # OR pattern
    ({lvasgn lvar} :hash _) # Either a local var or assignment
    (send nil? :hash)       # ...or a call to that variable
  } # End OR pattern
NODE

hash_match.match(ast_of("hash = {}"))
  # => true

In fact this is how RuboCop autocorrect works by searching for a certain node and doing something when it's found.

Some of these tools have even already been wrapped, like Jonatas's work on FFast which works on top of NodePattern and some of RuboCop's previous work. Really the only things between us and this future is a bit more wrapping and polish, as well as integrations into something like VSCode.

Any takers? I may well wrap some of this in a more minimalist gem that provides an easier-to-use interface to build on, as the current parts are non-intuitive unless you're willing to dig into the code on a non-trivial basis.

EmberJS Style Codemods

There are a lot, and I mean a lot, of ideas we can and should be taking from Javascript in the Ruby community. One of them is the idea of code mods for migrating syntaxes, and especially for upgrades from old versions.

When I was working with EmberJS there were multiple codemods designed to make migrating from one version to the next, and it was a very pleasant experience. The idea was that after you upgraded dependencies you ran one command and most if not all of the upgrade was done for your syntax.

Why can't we have that in Ruby? Why not especially for Rails? Turns out the answer is that there are indeed some of these things already:

https://docs.rubocop.org/rubocop-rails/cops_rails.html

Notice that several of those support "autocorrection", meaning that running RuboCop with -a will fix them for you:

rubocop -a

Let's take a glance at the action_filter cop real quick here, but just a quick part of it:

def check_method_node(node)
  method_name = node.method_name
  return unless bad_methods.include?(method_name)

  message = format(MSG, prefer: preferred_method(method_name), current: method_name)

  add_offense(node.loc.selector, message: message) do |corrector|
    corrector.replace(node.loc.selector, preferred_method(node.loc.selector.source))
  end
end

Notice that after add_offense it uses corrector.replace to replace with a preferred method source. Not only that, but if we went over to the specs:

described_class::FILTER_METHODS.each do |method|
  it "registers an offense for #{method}" do
    offenses = inspect_source("#{method} :name")
    expect(offenses.size).to eq(1)
  end

  # ...

...we can see that there are even tests for it, meaning that we can not only describe and implement transformations, but programmatically test them so we don't have to manually rerun them on our entire codebases.

That's a lot of power. Imagine with me that new versions of Rails were bundled with autocorrectors which got people 90%+ done with a Rails upgrade, just from running one more command or potentially even bundling it in the official Rails upgrade process itself.

We could dramatically reduce the potential for manual errors, and make upgrading a substantially more seamless and painless process.

The secret here is that I do not believe this is far off, and there may well be people already doing this on the Rails core team.

Babel Transpiler

Another lesson we can and should take from Javascript is the Babel traspiler. Babel allows for the introduction of syntax before it's officially in the language, making it extremely effective for testing and experimentation of new language features. Proof-of-concepts can be more easily verified, and frequently TC-39 uses them in formal proposals.

Not only that, but the language can polyfill older versions with new features and enhancements, allowing developers to use features only present in newer versions more easily. For Javascript that's a huge deal as they have to deal with such variance in web browser support.

As it would happen, the folks behind Ruby Next have some ideas here, and have done a significant amount of work in enabling this very vision to become a reality.

They wrote quite a bit on that very topic here:

https://evilmartians.com/chronicles/ruby-next-make-all-rubies-quack-alike

...and a lot of those terms are going to look very familiar to what you've been reading already, and there's a very good reason for that.

A to B Inferred Transforms

Perhaps the most troublesome part of writing regex, and really any regular language, is getting the syntax right. The same is true of NodePatterns. Why can't we just say that we have code "A" here:

[1, 2, 3].select { |v| v.even? }

...and have it figure out the syntax to go to code "B" here?:

[1, 2, 3].select(&:even?)

For us as humans that seems pretty straightforward. If the block argument matches the body, and only one operation is happening directly on it, we can replace that with the shorthand block syntax.

What if we had a way to give code "A" and "B" and have Ruby find the transformations between the two?

For simple cases that algorithm might look like this:

Match the original syntax
Find similarities with the desired target syntax
Find what has changed
Identify which parts of the code moved where
Create matchers to capture moved parts in the original code
Create code to generate the target code
Profit

...but those are tree algorithms which are unfortunately beyond me at the moment. The implications, however, are staggering if this is pulled off. Having a meta-language that allows one to quickly generate code migration syntax would lower the barrier to entry of code migrations that can be bundled with upgrades, and also allow whole new methods of refactoring.

Perhaps I'll experiment with this more later, but at the moment it is most certainly beyond my skills. I would venture a guess that algorithms used to solve word ladders, or perhaps levenshtein/word distances, could be used here though.

Macros

Having a method to express A to B is great even in static files, but what if such things could be done in a running program?

If ASTs were accessible in running Ruby programs, we could potentially create syntax which could rewrite syntax.

Now if you're not familiar with the idea of macros from Crystal or LISP-like languages, you might wonder why you might care. One of the primary advantages is unfolding loops, allowing algorithms to go from O(n^2) to O(n), meaning massive performance benefits.

I'd written on this some time ago with matchable:

https://dev.to/baweaver/matchable-class-level-pattern-matching-macros-explained-32df

The particularly relevant part is replacing the idea of public_send with a directly inlined code-path:

valid_keys.each do |key|
  deconstructed_values[key] = ${key}
end

deconstructed_values

...as public_send is slow compared to directly calling a method. If taken to logical extremes one could not only inline the actual method call, but extract the method code and interpolate it directly into such a method.

There are already some techniques capable of doing just this, by combining Parser with Unparser, but of course such things can only be done on Ruby files read in rather than in a REPL session which is where a lot more fun could happen.

A live AST could really make a very interesting future here.

Wrapping Up

Now you might have noticed something particularly interesting with this article: Almost all of these items are either not that far off, or are already being used in production by several major players in the Ruby ecosystem.

The truth is the future has already been coming, and perhaps our issues are not as much around tooling, but in making the tooling more accessible and well understood to our community.

If this is combined with more official support from the Ruby core team, especially around the Whitequark and RuboCop parsers, I believe we'll take a great step forward. The challenge now is documentation, education, advocacy, and support.

I believe all of those are very possible.

Let's Read – Eloquent Ruby – Ch 6

Brandon Weaver — Tue, 02 Nov 2021 06:30:06 +0000

Perhaps my personal favorite recommendation for learning to program Ruby like a Rubyist, Eloquent Ruby is a book I recommend frequently to this day. That said, it was released in 2011 and things have changed a bit since then.

This series will focus on reading over Eloquent Ruby, noting things that may have changed or been updated since 2011 (around Ruby 1.9.2) to today (2021 — Ruby 3.0.x).

Note: This is an updated version of a previous unfinished Medium series of mine you can find here.

Chapter 6. Use Symbols to Stand for Something

This chapter covers one of the admittedly more confusing aspects of Ruby, Symbols. Still a bit confused about them yourself? Nothing to feel bad about on that, it took me a while before it clicked, and I can't say it's the most intuitive part of the language.

That said, we'll take a look at Russ's thoughts here in the book and add some new context that we've seen in later versions of Ruby that have further blurred the line, as well as some of the arguments on why Symbol and String will never be merged (and should not be).

The simplest description, however, you could use is that Strings are text meant for a human, and Symbols are labels meant for your program.

The Two Faces of Strings

The book starts in with an example that it deliberately simplifies by saying Symbols are really just Strings:

string = "dog"
symbol = :dog

In many senses and at first glance, as the book mentions, they're the same three characters referring to the same idea: a dog. In many cases in Ruby they could even be used interchangeably (though they shouldn't be), further confounding folks trying to understand what the differences are.

Take these two (old) Rails examples the book mentions:

book = Book.find(:all)
book = Book.find("all")

# Modern versions do this instead:
books = Book.all

The point is as a human we can tell we mean the same thing, and that's an important thing to realize about Ruby: It legitimately tries to not be surprising. If you could reasonably think a method could take a String or a Symbol chances are it will:

def testing; 1 end

method(:testing)
# => #<Method: main.testing() (irb):1>
method("testing")
# => #<Method: main.testing() (irb):1>
method(:testing) == method("testing")
# => true

That's certainly not the only time Ruby does this, but a good general rule is to use Symbols in these types of cases. We'll get into that more in a moment along with the book.

Not Quite a String

The book then goes on to ask why we need both, and presents an answer: Strings hold data that we're processing.

In the Rails example Book.all would return several records with String data in them. Data that could be changed, read, or acted upon by humans.

For Symbols in the (outdated) example of Book.find(:all) we're using :all as a flag for what records to retrieve, or in the case of method which method in the program we're retrieving. Those Symbols stand for an idea, and serve as a named label for the concept.

The book then mentions Symbols could also be thought of as a very pared down String. Symbols don't particularly need manipulation, so all the methods for transforming and working with Strings don't make sense in the context of labeling something internal to the program.

Because of those assumptions Symbols can be optimized. Granted in more recent versions of Ruby with frozen Strings this difference is not nearly as pronounced.

Optimized to Stand for Something

Next up the book gets into the optimization implications we'd started to mention. Strings are optimized for data processing, and symbols are optimized for equality checks.

In its example we have a few variables assigned to Symbols:

a = :all
b = a
c = :all

[a, b, c].map(&:object_id)
#  => [784988, 784988, 784988]

a == c
# => true
a === c
# => true
a.eql?(c)
# => true
a.equal?(c)
# => true

They're all the exact same entity. The book then goes on to say that this isn't the case for Strings:

x = "all"
y = "all"

That's not strictly true any more with the frozen string literal comment:

# frozen_string_literal: true

x = "all"
y = "all"

...but we'll leave that alone for now and get back to the book. In the case where this is not enabled both of these Strings are in fact different objects, whereas there can only ever be one instance of any given Symbol.

Symbols are also immutable (Strings can be frozen, or use the frozen_string_literal comment above). That's why they tend to be used for Hash keys.

Hash implements a few things behind the scenes to make sure that mutated keys don't crash programs, and as the book mentions this is most certainly a patch against Strings being mutable and potentially causing issues.

In the Wild

The book then goes on to mention that yes, they're confusing, and lists a few more examples.

In one you can convert between the two using to_sym and to_s, and in a significant amount of Ruby methods they'll even do this behind the scenes if they think you might reasonably use them interchangeably. Does that make it correct? Perhaps not, but it's such a common issue that we're probably pretty far beyond that by now.

In older versions of Ruby (older than 1.9) asking for the public methods of an object used to return a String Array, but now returns Symbols, so even Ruby itself has some issue keeping track. Then again 1.8 to 1.9 was a pretty big gap, whereas 1.9 to 2.0 and 2.7 to 3.0 were far more minor.

Staying Out of Trouble

One of the most common issues is going to come back to Hashes using Symbol and String interchangeably. If you did, they would break. person[:name] is not the same as person["name"] unless you have a HashWithIndifferentAccess from Rails which hacks around this.

Personally, and there are going to be a number of people who consider this heretical, I believe that most Hash keys should be Strings unless that Hash is being used internal to the program. That said, enforcing semantic style that requires any type of human interpretation is perilous, so I would never try and make that happen.

Some have even tried to add JS object style where person.name is the same as person[:name] or person["name"] using Hashie, but the author and several other Rubyists came to the conclusion that this wasn't a great idea.

Schneems wrote on this years ago, and it would be a good article to read into:

https://www.schneems.com/2014/12/15/hashie-considered-harmful.html

Wrapping Up

Symbols and Strings aren't getting merged. That ship has sailed many times and has been rejected every single time. You can read more into it, but by now it's one of those features for better or worse that's part of the language.

Deprecating features is not easy, and there are a number of them even Matz has said he regrets adding. That said, knowing that when writing something requires insight beyond what any programmer can reasonably be expected to have, and years of development on the feature to prove the point.

Compatibility and non-breaking changes are critically important to a programming community, and I believe Matz and crew have made the correct decision on this, even though I may protest on principal.

Let's Read – Eloquent Ruby – Ch 5

Brandon Weaver — Tue, 19 Oct 2021 09:29:36 +0000

This series will focus on reading over Eloquent Ruby, noting things that may have changed or been updated since 2011 (around Ruby 1.9.2) to today (2021 — Ruby 3.0.x).

Note: This is an updated version of a previous unfinished Medium series of mine you can find here.

Chapter 5. Find the Right String with Regular Expressions

This chapter focuses on Regular Expressions, or Regex for short. It's one of the most powerful concepts in programming around text manipulation, but also probably one of the most confusing.

If you haven't already heard of these two I would highly suggest using them while exploring Regex:

Rubular - Basic Ruby-centric Regex tester
Regexr - More advanced, explains each segment of a Regex

Personally I tend to use Rubular more, but mostly because the extra info Regexr presents is a bit too noisy for me. In either case I would highly suggest running examples from this chapter and experimenting with them in either tool.

With that said, let's get into it.

Introductory Examples

The chapter opens with a few examples, like to start with why do you want Regex? The book uses the String "09:24 AM" as an example. How can you tell it's a time? AM or PM? 24H or 12H? Maybe even ambiguous. These are a lot of questions that can be a bit difficult to answer with just String methods, requiring something a bit more powerful.

Think of Regex like a method of describing the shape of text. "09:24 AM" is composed of two digits, a colon, two digits, a space, and AM or PM. Regex is a language that lets us say exactly that:

# Regex starts and ends with a `/`, or surrounded by %r{}
time_match = /\d{2}:\d{2} (AM|PM)/
# time_match = %r{\d{2}:\d{2} (AM|PM)}

time_match.match? "09:24 AM"
# => true

Now that's all a bit dense to start out with, so let's step back along with the book to get into a few more examples.

Matching One Character at a Time

The book lists a few examples, but let's turn those into code real quick:

# The regular expression x will match x.
/x/.match? "x"
# => true

# The regular expression aaa will match three a’s all in a row.
/aaa/.match? "aaa"
# => true

# The regular expression 123 will match the first three numbers.
/123/.match? "123"
# => true

# The regular expression R2D2 will match the name of a certain sci-fi robot.
/R2D2/.match? "R2D2"
# => true
/R2D2/.match? "r2d2"
# => false (case sensitive)

Special Characters

Now those could all have been == compares instead, so let's look at a few more interesting characters:

. - Matches any one character.
* - Matches zero or more of whatever comes before it.
+ - Matches one or more of whatever comes before it.

Going back to examples:

# The regular expression . will match any single-character
# string including r and % and ~.
dot_match = /./

dot_match.match? "r"
# => true
dot_match.match? "%"
# => true
dot_match.match? "~"
# => true

# In the same way, two periods ( .. ) will match any two characters,
# perhaps xx or 4F or even [!, but won’t match Q since it’s one,
# not two, characters long.
double_dot_match = /../

double_dot_match.match? "xx"
# => true
double_dot_match.match? "4F"
# => true
double_dot_match.match? "[!"
# => true
double_dot_match.match? "Q"
# => false (one character)

Literal Characters

There are some characters you want to match an actual dot, so how does one get Regex to do that? With a backslash:

# \. will match a literal dot.
/\./.match? "."
# => true

# 3\.14 will match the string version of PI to two decimal places,
# complete with the decimal point: 3.14
/3\.14/.match? "3.14"
# => true

# Mr\. Olsen will match exactly one thing: Mr. Olsen
/Mr\. Olsen/.match? "Mr. Olsen"
# => true

Combining Effects

The book then goes into a few combos, let's turn those into examples:

# The regular expression A. will match any two-character string that
# starts with a capital A, including AM, An, At, and even A=.
a_dot = /A./

a_dot.match? "AM"
# => true
a_dot.match? "An"
# => true
a_dot.match? "At"
# => true
a_dot.match? "A="
# => true

# Similarly, ...X will match any four-character string that ends
# with an X, including UVWX and XOOX.
x_match = /...X/

x_match.match? "UVWX"
# => true
x_match.match? "XOOX"
# => true

# The regular expression .r\. Smith will match both Dr. Smith as
# well as Mr. Smith but not Mrs. Smith.
smith_match = /.r\. Smith/

smith_match.match? "Dr. Smith"
# => true
smith_match.match? "Mr. Smith"
# => true
smith_match.match? "Mrs. Smith"
# => false

Sets, Ranges, and Alternatives

Say you wanted a character out of a set of them, Regex enables this with []:

vowel_match = /[aeiou]/
digit_match = /[0123456789]/
hex_match = /[0123456789abdef]/

Think of them as inclusion in a set of characters. The book then goes on into a few more examples here:

# The regular expression [Rr]uss [Oo]lsen will match my name, with or without
# leading capitals.
/[Rr]uss [Oo]lsen/.match?("Russ Olsen")
# => true

# More practically, you could use [0123456789abcdef][0123456789abcdef] to
# pick out a two-digit hexadecimal number like 3e or ff.
two_digit_hex_match = /[0123456789abcdef][0123456789abcdef]/
two_digit_hex_match.match?("3e")
# => true
two_digit_hex_match.match?("ff")
# => true

# You can also use [aApP][mM] to match am or PM and anything in between,
# like aM or Pm.
meridiem_match = /[aApP][mM]/
meridiem_match.match?("am")
# => true
meridiem_match.match?("AM")
# => true
meridiem_match.match?("aM")
# => true
meridiem_match.match?("pm")
# => true
meridiem_match.match?("pM")
# => true

Ranges

Now if that all seems a bit tedious there's the concept of a range in Regex:

/[a-z]/.match?("x")
# => true

/[0-9]/.match?("4")
# => true

Common Set Shortcuts

...and the even more useful common set shortcuts:

# Any number
/\d/.match?("0")
# => true

# Any letter, number, or underscore
/\w/.match?("c")
# => true

# Any whitespace like space, tab, and newline
/\s/.match?(" ")
# => true

Alternatives

The last in this section is the alternative, which you can think more of as "OR":

# A|B will match either A or B.
/A|B/.match?("A")
# => true
/A|B/.match?("B")
# => true

# AM|PM will match either AM or PM.
/AM|PM/.match?("AM")
# => true
/AM|PM/.match?("PM")
# => true

# Batman|Spiderman will match the name of one of the two superheros.
/Batman|Spiderman/.match?("Batman")
# => true
/Batman|Spiderman/.match?("Spiderman")
# => true

The book goes on to mention that you can use as many alternatives as you would like, but also sneaks in group captures (()) here which I don't believe it gets into later, but trust me when I say that's one of the most useful parts of Regex.

The Regular Expression Star

Interestingly we mentioned this above in special characters, the star (*) stands for zero or more of whatever is before it, and the plus (+) stands for one or more. There's one more idea here with specifying count, but that's an item for later.

The book mentions the following examples:

# AB* will match AB—that’s an A followed by one B.
/AB*/.match?("AB")
# => true

# AB* will also match ABB as well as ABBBBBBBB—remember, it’s an A followed
# by any number of B’s.
/AB*/.match?("ABB")
# => true
/AB*/.match?("ABBBBBBBB")
# => true

# Don’t forget that AB* will also match plain old A—any number of B’s
# includes no B’s at all.
/AB*/.match?("A")
# => true

If we were to switch to + that last case wouldn't work. The book then goes on to mention that sets, ranges, and common sets work with * as well. Really, anything does:

# Zero or more vowels
/[aeiou]*/

# Zero or more numbers
/[0–9]*/
/\d*/

# Zero or more hex digits, lowercase
/[0-9a-f]*/

# Zero or more of any character
/.*/

That last one the book mentions can be extremely useful, and is frequently used to make more flexible patterns:

/George.*/.match?("George Smith")
# => true

/.*George/.match?("Sally George")
# => true

/.*George.*/.match?("Jimmy George Joeseph")
# => true

Personally I would advocate for being more explicit about what you expect, lest you match more than you intended. Perhaps you do want to match a lot more, that's fine too, but make sure that's the case.

Regular Expression Counts

The book does not mention this, but it's an important subject to bring up: counts. Star is used for zero or more, plus for one or more, question for optional, but what about if I wanted something like 4 to 5 instances?

There are four count matches you'll want to be aware of:

# Exactly 3 of a
/a{3}/.match?("aaa")
# => true

# 3 or more of a
/a{3,}/.match?("aaaa")
# => true

# Between 3 and 6 of a
/a{3,6}/.match?("aaaaa")
# => true

# Up to 6 of a
/a{,6}/.match?("aaaaa")
# => true

Do note though that unless used in conjunction with the section "Beginnings and Ends" coming up it won't work as intended, so be sure to give that a look and see if you can spot the flaws in the above matches.

Regular Expressions in Ruby

Up to this point the book is just mentioning the Regex language without really getting into the Ruby implementation. For me and this article, however, I used Ruby implementations to show how it would work, so a lot of this will seem familiar.

I'll give an overview instead of what it mentions.

Equal Squiggly (`=~`)

The equal squiggly sign is used for matching in Ruby, though it's not the clearest syntax:

/\d\d:\d\d (AM|PM)/ =~ '10:24 PM'
# => 0

Why zero? That's the position in the string it found the match at. If there was nothing in there we'd get nil back instead.

Personally I prefer match? as it returns back an explicit true or false, is faster, and very rarely do I need to know the direct index of something.

Regex Flags

The book does sneak a fast one in here with Regex flags like i which makes things case-insensitive:

merediem_match = /AM|PM/i

merediem_match.match?("am")
# => true
merediem_match.match?("pm")
# => true

There are several more you can find at the bottom of rubular, but the common ones I use are i for case-insensitive and x for whitespace-insensitive.

Methods Taking Regex

There are also methods like sub, gsub, scan, and others which take in a Regex, like this example the book provides:

class Document
  # ...

  def obscure_times!
    @content.gsub!(/\d\d:\d\d (AM|PM)/i, "**:** **")
  end
end

Note: I did add the i there, where the book omits it. Case-insensitive would be more flexible here.

Beginnings and Ends

The book then mentions that the Regex we've used so far are unbounded, meaning they match anywhere in a string. There are a few more special expressions that allow us to specify beginning and end of line, and beginning and end of strings:

# Matches beginning of String
/\ASome text/.match?("Some text starts this")
# => true

# Matches end of String
/Some text\z/.match?("ends with Some text")
# => true

# Matches beginning of any line in a string
/^Some text/.match?("Other text\nSome text")
# => true

# Matches end of any line in a String
/Some text$/.match?("Some text\nOther text")
# => true

Especially when dealing with user input you want to be exceptionally strict about this, and most Rails security tools are going to give you grief over omitting explicit beginning and ending of String signifiers in your Regex.

In the Wild

The book mentions a real-world usecase as timezone offsets in time.rb, notedly numeric ones like -07:00 or +08:00, with this line:

if /\A([+-])(\d\d):?(\d\d)\z/ =~ zone

The book mentions question mark (?) as being an optional character, meaning there could be a colon there, or there could not be.

Now the interesting part, and what the book wants to highlight, is that if the Regex isn't matched it's compared against a set of values like UTC:

elsif ZoneOffset.include?(zone)

...which mixes the usefulness of Regex with the usefulness of set inclusion. That said, one could also do this:

zome_offset_matches = Regexp.union(*ZoneOffset)

...which I've gotten a good deal of mileage out of in the past

Staying Out of Trouble

The book mentions watching out for using == accidentally in place of =~, though to avoid that I would still actively recommend using match? instead as clear naming means a lot when reading your code later.

The second it mentions is 0 being falsy in C-like languages, despite being truthy in Ruby and representing something was found at the 0th index of a String.

Wrapping Up

There's a ton to cover any time Regex comes up, and the book gives a solid start, though I do really wish they had spent a bit of time on capture groups and counts.

I may do a writeup or addendum to this chapter later on capture groups if there's interest, let me know!

Next up we'll have Symbols, one of the more confusing aspects of Ruby.

Tales of the Autistic Developer - Loud Loud World

Brandon Weaver — Sun, 17 Oct 2021 06:14:37 +0000

For those who don't know me, I'm autistic. I've been a developer for the better part of a decade.

I write these posts in the hopes that someone like me will find value in knowing a very simple and very important truth about ASD:

You are not alone, and you are loved.

Loud Loud World

For autistic people the world is so very loud, and I fear that this has led to a very common misunderstanding of our experience.

It's not that we lack the capacity for things like listening, eating, empathy, or so many other skills as much as we're in a near-constant state of being overwhelmed by everything around us.

This post is less about solutions, and more about my experience as a disability. So many would like to frame what I have as a "superpower" but deny the handicaps I face, so I'd like to take this time to write on the struggles I face on a daily basis.

I Can Hear Everything

A common complaint of myself as a child is I was never paying attention, would frequently ask folks to repeat things, and in general just not "hear".

Ironically I was also mocked for having near supernatural hearing abilities. If my name was mentioned or any other trigger word for a hobby I would hear it, even clear across a room.

The misconceptions of the first section are a direct result of the second. It's not that I couldn't hear, but that I heard too much.

My brain is constantly on, and I experience everything at once. I can't turn it off, I don't know how and there aren't any great solutions I've found beyond noise cancelling headphones and moving out of noisy environments.

Heck, I can hear electricity in the walls. Did you know it makes noise, because I certainly do. A short in an electronic device will scream at me, and with it my focus goes right out a window.

I'm most certainly not ignoring you when you're talking, in fact I'm reminding myself to pay attention in my head on repeat, but if a loud noise or something troubling happens my attention is gone. You could talk about my favorite hobbies and I'd still twitch at anything around me happening, try as I might to stop it.

Smell Everything

In elementary school I was quite viciously mocked for smelling things, including by a teacher who egged it on. A lot of trauma in me realizing who I was could be traced to teachers like this, but back to the point I could smell anything around.

If lunch was being prepared I could tell you exactly what it was (if I'd experienced it before), what burned, what flavor the gum under the table probably was, and whether or not my classmates had just been to gym class.

Just in the past year I'd smelled rain and heard a dropping that led me to find a small leak in one of the doors of my home.

It wasn't unusual for this to make me slightly sick, as scent is very closely tied to taste.

Any more I've taken to a habit of wearing a certain amount of cologne as a centering scent to try and distract me from doing this. Most of my coping follows a similar strategy of dulling my senses.

Taste Overload

Some would call me a picky eater, they're probably right. If something is unfamiliar to me it's overwhelming, and certain textures and combinations for some reason will make me physically sick.

The annoying part is that I don't always know what those textures or combinations might be.

It's been a perpetual fear of mine that I might offend someone by not being able to eat their cooking, so many times I'll try anyways and end up making myself sick for a few days afterwards.

Back in college there was an eating competition where they gave us tacos with lettuce. Those who know me would know that that's one thing which will absolutely make me visibly sick within seconds, so I had to drop out.

This certainly does not make it easy to find a balanced diet, and trust me I do try. It's also why I order the exact same thing every time I go to the same restaurant. I know it's safe, and safe matters a lot to me, which is how I cope.

Visual Stimulus

Now I'm not at the point of epilepsy, but flashing gifs and reactions will wreck my concentration. I'm very happy that Slack added an option to turn them off or I'd never get anything done.

My vision isn't perfect, I wear glasses, but any visual stimulus around me sends my head into full alert mode. It's also why you'll catch me closing one eye outside, or closing both if I'm thinking.

Touch and Feel

There are even fabrics and various textures that if I touch or have to keep on I get very uncomfortable with. Fabric tags, wools (especially socks), seams, and other things some folks can ignore will drive me up a wall.

If there's so much as a small pebble that gets into my shoe it's going to annoy me the entire day until I get it out, including ones embedded in the bottom of my sole.

Emotional Overload

People have called me a robot for years, slightly monotone voice, and a seeming absence of cognizance of emotions. Sure, there's some truth to that, I don't social well all the time and I had to learn those rules the hard way.

What isn't true, however, is that I don't feel. Quite the contrary.

I have to turn off news, social media, and stop talking to people because once I hear problems I become deeply invested in fixing them. My mind is hard-wired like that, I want to help, and I'm far too easy to bait into things.

As a result I've had to become exceptionally cautious in how much I talk to others outside of close groups. The real annoyance is I can feel their pain, but I have no idea how to respond appropriately, so rather than try I frequently have to wait and internalize that pain which is not healthy.

I hate that I cannot fix everything, so instead I try and focus on what I know I can have an impact on and direct my attentions there. Doesn't help that sick feeling though knowing how much more pain there is in the world.

Temporal Hijinks

I have no concept of time. People at work would disagree with me on that and comment that I show up early to things, know exactly when things are happening, and am generally on top of it.

That's only because I have alarms for everything, calendar reminders, sticky notes, and entire systems meant to keep me on track. I adhere to strict schedules, and should I break those schedules I'll burn out hard and lose my sense of self for at least a few weeks while I recover and recalibrate.

It's a similar reason to why I despise phone calls and synchronous events which require presence, as they'll ruin the entire rest of my day for getting anything done.

The irony, as it tends to be, is that all of these systems got me promoted into roles where it's my job to be on top of such things.

The Migraines

When the world is too much, when anxiety gets to me, and when I just can't turn it off my body will eventually take drastic measures and start me into a series of migraines that will have me laid up in bed for at least a full day, often times two to three days.

As I get close to that point I will be very short tempered and intentional with my time, trying to jettison anything and everything that's not completely relevant to tasks at hand that are required to get done. I start going into lockdown mode to protect myself, and if I miss I'm going to be out of it for potentially multiple days.

If I keep ignoring it? Burnout is a very real threat for me, and one that I have to be exceptionally cautious of. Some would say enjoying what you do is a cure, but if anything that's the curse which has me constantly flirting with the line where I'm not coming back for a good couple of months beyond rote and repetition.

Wrapping Up

If there's one thing I want people to get out of this, it's that I'm a whole human. You don't get all the benefits of autism without the drawbacks, and the drawbacks make you no less valid of love and acceptance.

Over the years I've had great success in the industry, but many would erase my disability, and in doing such they would discriminate against those with similar issues. To only write of the good, and never the bad, would be dishonest.

So I wrap up today by saying that I'm me, flaws and all. It's a loud loud world out there, and we do our best to participate in it.

Let's Read – Polished Ruby Programming – Ch 3.2 Instance Variables

Brandon Weaver — Tue, 28 Sep 2021 05:57:22 +0000

Polished Ruby Programming is a recent release by Jeremy Evans, a well known Rubyist working on the Ruby core team, Roda, Sequel, and several other projects. Knowing Jeremy and his experience this was an instant buy for me, and I look forward to what we learn in this book.

You can find the book here:

https://www.packtpub.com/product/polished-ruby-programming/9781801072724

This review, like other "Let's Read" series in the past, will go through each of the chapters individually and will add commentary, additional notes, and general thoughts on the content. Do remember books are limited in how much information they can cram on a page, and they can't cover everything.

With that said let's go ahead and get started.

Chapter 3 – Proper Variable Usage – Instance Variables

The third chapter covers the following topics:

Using Ruby's favorite variable type – the local variable
- Increasing performance by adding local variables
- Avoiding unsafe optimizations
- Handling scope gate issues
- Naming considerations with local variables
Learning how best to use instance variables
- Increasing performance with instance variables
- Handling scope issues with instance variables
- Naming considerations for instance variables
Understanding how constants are just a type of variable
- Handling scope issues with constants
- Visibility differences between constants and class instance variables
- Naming considerations with constants
Replacing class variables
- Replacing class variables with constants
- Replacing class variables with class instance variables using the superclass lookup approach
- Replacing class variables with class instance variables using the copy to subclass approach
Avoiding global variables, most of the time

We'll be covering instance variables in this section.

Increasing performance with instance variables

As with the section on local variables you can also increase performance using instance variables, but primarily through caching techniques. The book mentions this in terms of idempotency and storing the results of calculations, but personally I prefer cache as a more approachable term.

It then goes to this example:

LineItem = Struct.new(:name, :price, :quantity)

class Invoice
  def initialize(line_items, tax_rate)
    @line_items = line_items
    @tax_rate = tax_rate
  end

  def total_tax
    @tax_rate * @line_items.sum do |item|
      item.price * item.quantity
    end
  end
end

It mentions that if total_tax is only called once then there's not much value in caching, but if it gets called multiple times it could be worthwhile as the next example shows:

def total_tax
  @total_tax ||= @tax_rate * @line_items.sum do |item|
    item.price * item.quantity
  end
end

Before we continue with the book you'll notice common convention here is to use the name of the method as the name of the instance variable. I've also seen @_total_tax as an indication that it's a "private" instance variable rather than one that should be freely accessed, but that comes down to preference.

The book goes on to mention cases where ||= won't work, which is a very useful topic as I've seen that trip people a lot in production code. Those cases are around false and nil, and cases where those are legitimate return values you want to remember versus ones you want to override. The book mentions defined? as a way around this with a guard statement:

def total_tax
  return @total_tax if defined?(@total_tax)

  @total_tax = @tax_rate * @line_items.sum do |item|
    item.price * item.quantity
  end
end

Now for that particular case it won't make sense for that above concern, but it does prevent that false or nil issue when it comes up for other caching concerns.

The book also mentions here that defined? is more easily optimized by Ruby over instance_variable_defined?, as the former is a keyword rather than a Ruby method.

The other case where that caching technique will break is around frozen classes, which may be rarer. The books solution is as follows:

LineItem = Struct.new(:name, :price, :quantity)

class Invoice
  def initialize(line_items, tax_rate)
    @line_items = line_items
    @tax_rate = tax_rate
    @cache = {}

    freeze
  end

  def total_tax
    @cache[:total_tax] ||= @tax_rate * @line_items.sum do |item|
      item.price * item.quantity
    end
  end
end

Personally I find this against the spirit of freezing as you're modifying the internal Hash. If someone was going for purity here they'd likely return a new frozen instance with that variable pre-populated.

As with the previous example set this one is also weak to false or nil values which can be combated as such with key? in the place of defined?:

def total_tax
  return @cache[:total_tax] if @cache.key?(:total_tax)

  @cache[:total_tax] = @tax_rate * @line_items.sum do |item|
    item.price * item.quantity
  end
end

The book goes on to mention that when dealing with instance variables you do not have control over them as completely as you might with a local. What's to stop someone from modifying @tax_rate somewhere else? Not much in Ruby.

It also mentions that data being passed in could also be changed which can cause issues with caching:

line_items = [LineItem.new('Foo', 3.5r, 10)]

invoice = Invoice.new(line_items, 0.095r)

tax_was = invoice.total_tax

line_items << LineItem.new('Bar', 4.2r, 10)

tax_is = invoice.total_tax

...which is a great point to make, as some get too eager in caching and don't consider potential legitimate cases where values can change. In this particular one it's not the intent of the program, so it's more a negative thing.

The book mentions getting around this by getting a cleanly duplicated copy of the line items:

def initialize(line_items, tax_rate)
  @line_items = line_items.dup
  @tax_rate = tax_rate
  @cache = {}

  freeze
end

...or using line_items.freeze instead. Or even just using the best of both by using line_items.dup.freeze to more completely guard against shenanigans.

Ah, speaking of shenanigans, someone could modify the line items themselves as the book mentions:

line_items = [LineItem.new('Foo', 3.5r, 10)]
invoice = Invoice.new(line_items, 0.095r)
tax_was = invoice.total_tax

line_items.first.quantity = 100

tax_is = invoice.total_tax

...in which the solution is to make sure line items are also frozen:

LineItem = Struct.new(:name, :price, :quantity) do
  def initialize(...)
    super

    freeze
  end
end

...or to freeze them in the Invoice#initialize method:

def initialize(line_items, tax_rate)
  @line_items = line_items.map do |item|
    item.dup.freeze
  end.freeze

  @tax_rate = tax_rate
  @cache = {}

  freeze
end

Turns out caching is hard, frozen objects can make it somewhat easier, but a particularly determined person can find a way either explicitly or inadvertently. It's definitely good to cover the myriad of concerns that can go wrong in terms of caching, as it's a very hard problem in all of programming in general.

Handling scope issues with instance variables

Unlike local variables instance variables are scoped to the receiver, or self, as the book mentions. For me that's always meant that an instance variable is fetched from the context it's evaluated in, but for most folks the concern stops that it's seen in the scope of the current instance of a class they're working with.

Why the extra complexity there? Well there are some parts of Ruby that can change the context being evaluated like define_method, Class.new, Module.new, and a few others the book doesn't get into like instance_eval and friends where you can play with the binding.

The book mentions that instance variables can be in a different context, and the example it gives is a block passed to something you don't own:

class Invoice
  def line_item_taxes
    @line_items.map do |item|
      @tax_rate * item.price * item.quantity
    end
  end
end

Now for this one map isn't doing anything particularly odd, but that's assuming as the book says that @line_items is an Array containing LineItem objects which happen to respond to certain methods. Usually, a fairly safe assumption, but the book goes into when it might not be:

class LineItemList < Array
  def initialize(*line_items)
    super(line_items.map do |name, price, quantity|
      LineItem.new(name, price, quantity)
    end)
  end

  def map(&block)
    super do |item|
      item.instance_eval(&block)
    end
  end
end

Invoice.new(LineItemList.new(['Foo', 3.5r, 10]), 0.095r)

The book goes into the reasoning you might want to do this, but breaking down the code for a moment first:

super(line_items.map do |name, price, quantity|
  LineItem.new(name, price, quantity)
end)

# Potential variations:
line_items.map { |*args| LineItem.new(*args) }
line_items.map(&LineItem.method(:new))

This will convert any item passed in into a LineItem and forward it on to the Array constructor.

The next part on map is a bit more interesting:

def map(&block)
  super do |item|
    item.instance_eval(&block)
  end
end

It'll forward to the underlying map, but evaluates the block not in the context of the class, but in the context of the item itself. Why? Well the book gets into that.

The reasons provided are:

Ease of Initialization - Faster to create items via Array than manually constructing each one.
Ease of Access - Provides direct access to methods in the instance
Less Verbosity - Allows omission of item

For point 3 the following code is provided:

line_item_list.map do
  price * quantity
end

# Versus the more verbose:
line_item_list.map do |item|
  item.price * item.quantity
end

The book goes on to mention that this breaks the above example:

class Invoice
  def line_item_taxes
    @line_items.map do |item|
      @tax_rate * item.price * item.quantity
    end
  end
end

@tax_rate is no longer visible. There are workarounds with local variables like so:

class Invoice
  def line_item_taxes
    tax_rate = @tax_rate
    @line_items.map do |item|
      tax_rate * item.price * item.quantity
    end
  end
end

But as the book mentions, and I would agree, you're deviating far enough from common-use Ruby to be obtuse. The brevity you gain comes at the loss of intuitive clarity in your code, and should give a developer pause before trying such solutions.

A small amount of verbosity is a very fair trade for making code easier to understand, work with, and intuitively grasp its underlying structures. A good rule to keep in mind is to do the least surprising thing possible, because one day you may very well be the one surprised by your own code.

Naming considerations for instance variables

As with the previous section there really aren't too many differences in naming conventions between instance and local variables. They should be @snake_cased, and prefer ASCII characters. The book mentions some potential exceptions around mirroring @ClassNames and @ModuleNames, but I would almost discourage that myself in favor of remaining consistent with @snake_case.

The benefit of instance variables, as mentioned, is that they come with inherent context. That means you can name them a bit more loosely than you might a local variable. A few examples are provided:

# Too long
@transaction_processing_system_report = TransactionProcessingSystemReport.new

# Better
@tps_report = TransactionProcessingSystemReport.new

# Best, if only one report is present
@report = TransactionProcessingSystemReport.new

Wrap Up

With that we're finished up the section on instance variables.

The next section will cover constants.

Let's Read – Eloquent Ruby – Ch 4

Brandon Weaver — Tue, 21 Sep 2021 06:55:44 +0000

This series will focus on reading over Eloquent Ruby, noting things that may have changed or been updated since 2011 (around Ruby 1.9.2) to today (2021 — Ruby 3.0.x).

Note: This is an updated version of a previous unfinished Medium series of mine you can find here.

Chapter 4. Take Advantage of Ruby’s Smart Strings

This chapter starts into Strings, and the intro mentions something that I've found to be very true. Most folks would assume that programmers deal primarily in numbers, which sure we do, but far more often we're doing some form of text manipulation.

Parsing data, serializing it back, user input, really so much of programming centers around text and Strings, where a lot of the rest of it ends up around collections. For me numbers are almost a distant third to those two, but that's a personal opinion.

Coming Up with a String

So Ruby is Ruby, and the book mentions that there are several ways to make a String, much like so many other things in Ruby. Generally the easy rule to follow for me has been to use double-quotes for everything, despite the (completely insignificant) performance difference with single quotes.

Anyways, the book mentions a few examples of backslashes with single quotes:

# Escaping a single quote mark
a_string_with_a_quote = 'Say it ain\'t so!'

# Escaping a backslash
a_string_with_a_backslash = 'This is a backslash: \\'

Now the reason I say double quotes are going to be easier in general is that single quoted strings also treat things literally rather than evaluate special syntaxes:

single_quoted = 'I have a tab: \t and a newline: \n'
double_quoted = "I have a tab: \t and a newline: \n"

Same applies to interpolation, as the book mentions:

author = "Ben Bova"
title = "Mars"

puts "#{title} is written by #{author}"
# Mars is written by Ben Bova
#
puts '#{title} is written by #{author}'
# #{title} is written by #{author}

One weakness of quotes in general is when you get them mixed in each other, as the books next few examples mentioned:

str = "\"Stop\", she said, \"I cannot deal with the backslashes.\""

# versus using single quotes to wrap
str = '"Stop", she said, "I cannot deal with the backslashes."'

...but as with the book, I also agree that this is where the %q syntax is more useful:

str = %q("Stop", she said, "I can't live without 's and "s.")

It also gets into the fact you could have used %q[] or %q$$ or... anyways, probably best to prefer %q() in general as it's easier to deal with.

Now the next one to remember with %q is it's the same as single quotes, where %Q is double. As with my previous mention I would in general prefer double quotes unless you have a specific reason not to, or %Q in these cases.

The book then goes into Heredocs:

multi_line = <<EOF
Here's a lot of text. Some
of it goes on multiple lines!
EOF

The weakness here the book does not mention is that <<TAG syntax is space-sensitive:

m1 = <<EOF
Here's a lot of text. Some
of it goes on multiple lines!
EOF

m2 = <<EOF
    Here's a lot of text. Some
    of it goes on multiple lines!
EOF

So if you had some code like this:

module Container
  class Something
    def a_method
      puts <<EOF
        Text here that is slightly long
        because why not?
      EOF
    end
  end
end

...all that indent to the left? That's now in the String. You probably want the more recent "squiggly" heredoc syntax instead in general:

module Container
  class Something
    def a_method
      puts <<~EOF
        Text here that is slightly long
        because why not?
      EOF
    end
  end
end

There aren't very many good reasons to use << versus <<~, as the squiggly syntax auto-trims to the least indented line on the left, which is very very useful for long text.

Another API to Master

Stripping and Chomping

As with Array and so many other of Ruby's classes the real fun starts when you get into the methods they come with, and Ruby's String class has several. The book starts off with lstrip for one:

' hello'.lstrip
# => 'hello'

...and as intuition might serve, there's also an rstrip, and a strip which will take off of both ends. The more common one I use, and the book mentions, is chomp which gets rid of newline and carriage return characters at the end of a String:

"It was a dark and stormy night\n".chomp
# => "It was a dark and stormy night"

# ...but only one newline
"hello\n\n\n".chomp
# => "hello\n\n"

Now a method I always forget about, and haven't found much of a use for, chop:

"hello".chop
# => "hell"

...will knock off the last character no matter what it is. Personally I really haven't seen much of a use for this one, but that's me.

Case Manipulation

Next the book gets into working with string cases:

"hello".upcase
# => "HELLO"

"HELLO".downcase
# => "hello"

"Hello"
# => "hELLO"

More recent versions have also added capitalize:

"hello".capitalize
# => "Hello"

...which was formerly a Rails exclusive, but in common enough usage it makes sense.

Substitution

Next up is substitution, allowing you to replace part of a string with another:

"It is warm outside".sub("warm", "cold")
# => "It is cold outside"

...but that only works with one substitution. You'd want gsub for multiple:

"yes yes".sub("yes", "no")
# => "no yes"

"yes yes".gsub("yes", "no")
# => "no no"

Now be aware, the book doesn't mention this and leaves the bang (sub!, gsub!) variants of these methods to a bit later, but they have a dangerous difference.

So as a reminder bang methods do something worthy of caution, typically mutating the underlying object. In many cases they'll return nil if they make no modifications for optimization reasons, and the object if it does. That means chaining will throw you for a loop:

"abcd".sub!("ab", "ba").sub!("cd", "dc")
# => "badc"

"abcd".sub!("ac", "ba").sub!("cd", "dc")
# NoMethodError (undefined method `sub!' for nil:NilClass)

Catch that? Most won't while coding with these methods, and it can be a real pesky source of bugs. In general avoid bang methods unless you really need the performance increase. Most of the time you won't.

Splitting

Next up we have split, which allows us to split Strings on a character, or whitespace if unspecified:

"It was a dark and stormy night".split
# => ["It", "was", "a", "dark", "and", "stormy", "night"]

The book then gives an example of a character-based split:

"Bill:Shakespeare:Playwright:Globe".split(":")
# => ["Bill", "Shakespeare", "Playwright", "Globe"]

...but one thing is split actually takes two arguments, the delimiter (what separates items) and a count of how many items to max out on:

%Q(data: { "a": 1, "b": 2 }).split(":")
# => ["data", " { \"a\"", " 1, \"b\"", " 2 }"]

%Q(data: { "a": 1, "b": 2 }).split(":", 2)
# => ["data", " { \"a\": 1, \"b\": 2 }"]

Notice it? It's subtle, but because the String here is more of a key-value with the value being a JSON-like format it's not a good idea to split on : globally, but once, where the key and value are separated. Granted you should probably also do split(/: */, 2) to account for spaces between the two as well.

Lines, Characters, and Bytes

One topic that's come up a few times is why a String doesn't have an each method. Well, it does and it doesn't. What'd be the iterated item? Strings are a collection of a lot of different concepts. Bytes, characters, codepoints, lines, and probably a lot more I'm forgetting. Point being there's not one clear iterable here.

That's why Ruby lets you decide for yourself:

"some\nlines\nof\ntext".lines
# => ["some\n", "lines\n", "of\n", "text"]

"some\nlines\nof\ntext".each_line { |line| puts line }
# some
# lines
# of
# text
#  => "some\nlines\nof\ntext"

"abc".chars
# => ["a", "b", "c"]

"abc".each_char { |c| puts c }
# a
# b
# c
#  => "abc"

"abc".bytes
# => [97, 98, 99]

"abc".each_byte { |b| puts b }
# 97
# 98
# 99
#  => "abc"

"😅🎉✨".codepoints
# => [128517, 127881, 10024]

"😅🎉✨".each_codepoint { |c| puts c }
# 128517
# 127881
# 10024
#  => "😅🎉✨"

The book does mention that Ruby does allow Strings to be indexed against with [] like so:

"abc"[0]
# => "a"

...which implies it iterates on characters, but once you get into emoji and unicode and all the fun magics of non-ASCII Strings it starts getting a bit harder to work with.

Do also remember, as the book puts at the end of the chapter, that [-1] will get the last character and ranges are valid ([3..5]):

"some text"[-1]
# => "t"

"some text"[3..5]
# => "e t"

In the Wild

The book then goes into a few real-world examples of String manipulation, starting with html_escape from the standard library in the RSS library:

def html_escape(s)
  s
    .to_s
    .gsub(/&/, "&amp;")
    .gsub(/\"/, "&quot;")
    .gsub(/>/, "&gt;")
    .gsub(/</, "&lt;")
end

...though the Hash form may be a bit easier to work with later:

ESCAPED_ENTITIES_MAP = {
  "&"  => "&amp;",
  "\"" => "&quot;",
  ">"  => "&gt;",
  "<"  => "&lt;",
}

ESCAPED_ENTITIES = Regexp.union(ESCAPED_ENTITIES_MAP.keys)

def html_escape(s)
  s.to_s.gsub(ESCAPED_ENTITIES, ESCAPED_ENTITIES_MAP)
end

html_escape(%Q(<a href="link.html?a&b">text</a>))
# => "&lt;a href=&quot;link.html?a&amp;b&quot;&gt;text&lt;/a&gt;"

Useful to know that exists, anyways, back on topic.

The book then mentions a few Rails concepts, the inflector and the pluralizer. It's used to determine that the class inside current_employee.rb should be CurrentEmployee, and the associated DB table should be current_employee. As the book mentions this is done with String processing.

It works via a set of rules, especially around pluralization, like irregular pluralization cases like person pluralizing into people:

inflect.irregular("person", "people")
inflect.irregular("man", "men")
inflect.irregular("child", "children")
inflect.irregular("sex", "sexes")

...which are applied via gsub!, which uses that behavior of returning nil mentioned above:

inflections.plurals.each do |(rule, replacement)|
  break if result.gsub!(rule, replacement)
end

Now one could probably do this with find instead and avoid mutations, but knowing Rails and some of the optimization cases there there's probably a reason for it.

Staying Out of Trouble

Ruby Strings are mutable. There are ways around this with freeze and the frozen string literal:

# frozen_string_literal: true

"string".freeze

That means that any of those bang methods from above will mutate the underlying String:

first_name = "Susan"
given_name = first_name

first_name[-2..-1] = "ie"
# => "ie"

first_name
# => "Susie"

given_name
# => "Susie"

first_name.downcase!
# => "susie"

first_name
# => "susie"

given_name
# => "susie"

So be careful when mutating things unless you really really need it, but most of the time? You won't.

Wrapping Up

This wraps up chapter 4, which covers a lot of Strings in Ruby, but leaves some of the real interesting parts for chapter 5 where we get into Regex.

In the mean time? The book is correct, Strings are exceptionally common in Ruby, and dealing with them is going to be a substantial part of what you do in Ruby. Getting comfortable with those docs is certainly a wise investment.

Ruby 3.1 – Shorthand Hash Syntax – First Impressions

Brandon Weaver — Sun, 12 Sep 2021 05:09:51 +0000

It's the time of year again, and with it comes a bundle of new Ruby 3.1 features getting approved and merged ahead of the December release.

This series will be covering a few of the interesting ones I see going across the bug tracker. Have one you think is interesting? Send it my way on Twitter @keystonelemur or comment here.

Shorthand Hash Syntax - First Impressions

Now this, this is something I've wanted for a very long time. Shorthand Hash Syntax, also known as Punning in Javascript, is an incredibly useful feature that allows you to omit values where the variable name is the same as the key:

a = 1
b = 2

{ a:, b: }
# => { a: 1, b: 2 }

In Javascript this would like like so:

const a = 1
const b = 2

{ a, b }

So you can see some of the resemblance between the two.

Commits and Tracker

You can find the relevant diff here and the bugtracker issue here.

Exploring the Testcases

Let's take a look into the specs from that diff (slightly abbreviated):

def test_value_omission
  x = 1
  y = 2

  assert_equal({x: 1, y: 2}, {x:, y:})
  assert_equal({one: 1, two: 2}, {one:, two:})
end

private def one = 1
private def two = 2

Now as mentioned before, this allows value omission as specified in the first assertion:

x = 1
y = 2

assert_equal({x: 1, y: 2}, {x:, y:})

This is what I would expect the feature to do, and already opens up a lot of potential which I'll get into in a moment, but there's something else here in the second:

assert_equal({one: 1, two: 2}, {one:, two:})

# ...

private def one = 1
private def two = 2

...it's also working on methods, which opens up a whole new realm of interesting potential. I'll be breaking these into two sections to address what I think the implications of each are.

Implications of Punning

Let's start with general implications, as I believe those alone are interesting enough to write on.

Pattern Matching

Consider with me pattern matching:

case { x: 1, y: 2 }
# I do still wish `y` was captured here without right-hand assignment
in x:, y: ..10 => y then { x:, y: y + 1 }
# ...
end

This allows us to abbreviate the idea of leaving one value unchanged, and working with another value explicitly. In another case with a JSON response we might want to extract a few fields while changing one:

case response
in code: 200, body: { messages:, people: }
  { messages:, people: people.map { Person.new(_1) } }
in code: 400.., body: { error:, stacktrace: }
  { error:, stacktrace: stacktrace.first(5) }
# ...
end

It allows us to be more succinct in what we're simply extracting and what we're transforming.

Note: I have not tried combining this with regular Hash syntax, but I assume this will work given the parse.y code. More experimentation needed.

Keyword Arguments

Keyword arguments in general are a huge value-add to Ruby for understandability and errors:

# (A tinge contrived, yes)
def json_logger(level:, message:, limit: nil)
  new_message = limit ? message.first(limit) : message
  Logger.log({ level: level, message: new_message }.to_json)
end

With one argument that's not too bad, but the biggest annoyance of keyword arguments is constantly doing this:

some_method(a: a, b: b, c: c, d: d + 4)

It feels repetitive and doesn't add extra value. Punning in JS elided this information into arguments which should be forwarded without transformation, and Ruby shorthand hash syntax does the same. The benefits of keyword arguments without all of the extra code:

some_method(a:, b:, c:, d: d + 4)

Now we can quickly see only d is being modified, allowing us to more clearly see the intent of the code, while also getting all of the benefits of keyword arguments around name checks, value checks, and more easily understood methods.

I see this being the highest value add.

Implications of Including Methods

This one is a bit more unusual, but I like the idea.

Configuration Hashes

There are a lot of cases where I have to assemble larger hashes of configuration. By putting parts of it into methods I've made it easier to manage:

def configuration
  { a:, b:, c: }
end

private def a = {}
private def b = {}
private def c = {}

Those could be things like say logger configs, AWS keys, library configuration, and very interestingly (and I don't know if this would work) optional configuration cascades:

def configuration
  {
    **({ logger:, stack_limit:, tracing: } if logging.enabled?),
    **({ shards:, rw:, clusters: } if db.sharded?),
    # ...
  }
end

Of course those are theoretical and I would need to spend substantial time with this feature after nightly builds are out to be sure on this, but if it does work it opens the door for some very interesting cascading configuration styles in the future.

Wrap Up

This is a first impressions article on the shorthand hash syntax, and I expect as I have time to play with it I'll come up with some new ideas. Until then, I'll be watching the bug tracker for fun new features coming up soon.

Let's Read – Eloquent Ruby – Ch 3

Brandon Weaver — Tue, 07 Sep 2021 07:01:59 +0000

This series will focus on reading over Eloquent Ruby, noting things that may have changed or been updated since 2011 (around Ruby 1.9.2) to today (2021 — Ruby 3.0.x).

Note: This is an updated version of a previous unfinished Medium series of mine you can find here.

Chapter 3. Take Advantage of Ruby's Smart Collections

This chapter covers some of Ruby's collection classes and how to work with them. In Ruby this is probably going to be one of your most powerful and often used sets of libraries and features to work with, and in my early days I frequently found myself consulting this chapter and all the documentation related to it.

The book mentions here that if you were to look into any well-sized Ruby program you're going to find a ton of Arrays and Hashes scattered throughout, and all of the operations that occur on them. I've found this to be exceptionally true, and as mentioned above it's one of the most powerful parts of the language.

Enumerable's documentation is going to get a lot of reference as you learn Ruby and become more effective in it.

Literal Shortcuts

The book mentions a few ways of constructing an Array to start with:

# The normal way
poem_words = ['twinkle', 'little', 'star', 'how', 'I', 'wonder']

# Whitespace delimited words, same as the above
poem_words = %w{twinkle little star how I wonder}

Now one qualm I have with the book here is that {} can be confused with Hash later, and you're more likely to find common usage of either %w() or %w[] in its place. There are others, but by that point it's becoming a bit ridiculous. Personally I prefer %w(), but can see why the other is popular:

poem_words = %w(twinkle little star how I wonder)

The next bit covers Hashes, and the hash rocket (=>):

freq = { "I" => 1, "don't" => 1, "like" => 1, "spam" => 963 }

For String keys you'll find that in common use, but Symbol keys are a bit different:

book_info = { :first_name => 'Russ', :last_name => 'Olsen' }

book_info = { first_name: 'Russ', last_name: 'Olsen' }

They produce the same Hash, but one uses the 1.9.x "JSON-style" syntax. Very likely that syntax will look familiar as you find keyword arguments in methods as well, and it's generally preferred.

Personal Hill: Granted I really wish that Symbol keys would just be translated to String as this causes a lot of confusion for newer programmers for little gain, especially now that Strings are so commonly frozen. As always when I mention this I acknowledge there's 0% chance this changes, but I still find it a particularly frustrating part of Ruby.

Instant `Array`s and `Hash`es from Method Calls

The book goes on to mention ways of getting an Array or a Hash from a method call, in what is called a "splat" (*) or "keyword/hash splat" (**):

def echo_all(*args)
  args.each { |arg| puts arg }
end

def echo_at_least_two(first_arg, *middle_args, last_arg)
  puts "The first argument is #{first_arg}"
  middle_args.each { |arg| puts "A middle argument is #{arg}" }
  puts "The last argument is #{last_arg}"
end

Wherein the first is called a "varadic" method taking any number of arguments, and the second is much the same except that splat can be anywhere in the list. You can also do this on assignments:

a, *bs = [1, 2, 3]
# a = 1, bs = [2, 3]

a, *bs, c = [1, 2, 3]
# a = 1, bs = [2], c = 3

The book then goes on to mention explicit versus implicit Arrays:

class Document
  def add_authors(names)
    @author += " #{names.join(' ')}"
  end
end

class Document
  def add_authors(*names)
    @author += " #{names.join(' ')}"
  end
end

In the first case it would need to be called as such:

document.add_authors(%w(Jemisin Schwab))

...but the second might be:

document.add_authors('Le Guin', 'Hobb')

(Note that Ursula Le Guin would break that code's space delimiter, how might you fix it?)

The book then goes into a similar section on Hashes with load_font:

def load_font(specification_hash)
  # details omitted
end

load_font({ name: 'Helvetica', size: 12 })

If we happened to use the double-splat (or keyword splat, hash splat, or other names):

def load_font(**specification_hash)
  # details omitted
end

load_font(name: 'Helvetica', size: 12)

Warning: The book mentions that you can omit braces in the first case, but with Ruby 3.x+ this becomes complicated and is not recommended. Prefer to be explicit, and give the Ruby 2 Keyword Argument conundrum a read.

Running Through Your Collection

The book starts with a for loop example it quickly discourages afterwards:

words = %w(Mary had a little lamb)

for i in 0..words.size
  puts words[i]
end

# Though I think this is a more common variant to folks:
for word in words
  puts word
end

If you really want to know why you should avoid for in detail beyond "just use each" give this post a read, or just take our word for it on using each instead. The each variant of that code would be:

words.each { |word| puts word }

As the book mentions Hashes also have an each method:

movie = {
  title: '2001',
  genre: 'sci fi',
  rating: 10
}

# Single-argument yields the key and value as an Array
movie.each { |entry| pp entry }
# [:title, "2001"]
# [:genre, 'sci fi']
# [:rating, 10]

# This allows access to the key and the value:
movie.each { |name, value| puts "#{name} => #{value}" }
# title => 2001
# genre => sci fi
# rating => 10

Note: The book likes to use pp without mentioning it. It stands for Pretty Print, which is not really useful for most of the cases in this chapter, but can be for larger collections when you want it to be readable rather than a single-line you have to scroll to get through.

Now after this the book starts dropping hints for Enumerable and all the handy methods in it. Consider this, a potential method for finding the index of a word in a document:

def index_for(word)
  i = 0
  words.each do |this_word|
    return i if word == this_word
    i += 1
  end
  nil
end

Ruby has a lovely method which already takes care of this called find_index:

def index_for(word)
  words.find_index { |this_word| word == this_word }
end

Now I do have some slight qualms with the naming here, as word would be better as the iterated variable, and this_word could be the argument instead and renamed to target_word for intent, making this:

def index_for(target_word)
  words.find_index { |word| word == target_word }
end

...which personally I find a bit easier to read at a glance for a few reasons:

target_word makes the searched word more distinct than word
word is more suited to the generic word in a collection
Shifting word to the left gives it proximity to the block argument, making it easier to read left-to-right.

Now that last one is interesting, and will come up again in later sections. Proximity, and left-to-right, are very important in general readability of code and should be kept in mind. Names equally so.

If we had word at the end our eye has to go to the right to find where it's used, then back left to find what it's being compared to. Because word is more proximate to that scope it reads better when put first in that block.

I find this to be something I tend to do without thinking of it, but it has made code a lot easier to read at a glance and reduce jumping.

Anyways, back to the book, where we take a look into map which returns a new Array transformed by a block function:

[1, 2, 3].map { |v| v * 2 }
# => [2, 4 , 6]

The book uses this example of a hypothetical document, which I find a bit less clear for building immediate intuition:

doc.words.map { |word| word.size }
# => [3, 5, 2, 3, 4]

...and a way to lowercase all of those words:

lower_case_words = doc.words.map { |word| word.downcase }

It then goes into inject which I'll be using reduce instead as you'll find it more commonly in other languages (also foldLeft which isn't present in Ruby, but does more clearly articulate the function of the method).

The example the book uses is finding the average word length in a document:

class Document
  # The initial case, and the way you might approach it
  def average_word_length
    total = 0.0
    words.each { |word| total += word.size }

    total / word_count
  end

  # The same done with reduce
  def average_word_length
    # Yes, I swapped the order here to put result first
    total = words.reduce(0.0) { |result, word| result + word.size }
    total / word_count
  end
end

Now that's a bit hard to understand if you've never seen reduce before, so try this example real quick:

[1, 2, 3].reduce(0) do |accumulator, v|
  p accumulator: accumulator, v: v, new_accumulator: accumulator + v
  accumulator + v
end
# {:accumulator=>0, :v=>1, :new_accumulator=>1}
# {:accumulator=>1, :v=>2, :new_accumulator=>3}
# {:accumulator=>3, :v=>3, :new_accumulator=>6}
#  => 6

The idea is that reduce is reducing a collection of items into one item, in this case a number 0. accumulator starts as 0, and each loop becomes the value returned from the block function as we see in new_accumulator before the next loop. Whatever the value of the accumulator is at the end is the value we get returned.

If you want to read more into reduce take a look at this article where I explain it in more detail, and a conference talk I did called Reducing Enumerable which goes into far more detail.

Now that all said Ruby 2.4 introduced a method called sum which makes all of this much easier:

[1, 2, 3].sum
# => 6

...which makes that above document method look more like this:

class Document
  def average_word_length = words.sum(&:size).fdiv(word_count)
end

How's that for succinct? See this post and search for Ampersand (&) and to_proc for more information on that shorthand.

Note: fdiv is float division, which is more explicit than using 0.0 for an accumulator, or converting one of the values to a float.

There are still uses for reduce, sure, but I find they're rather rare and normally there are clearer methods to use in Enumerable you should consider first. That said, it's also exceptionally powerful and you could quite literally reimplement every other Enumerable method with reduce as well.

Chainsaws for trimming bonsai trees and such, use the least amount of power you need to get something done, and appearing clever surely isn't a valid reason to reach for a more powerful tool. Readability first, remember that one, it'll save you nightmares later.

Beware the Bang!

In Ruby a bang (ending with !) method is usually a warning sign, often related to a method mutating something or having some other side effect. Let's take a look at the book's example on reverse:

a = [1, 2, 3]
a.reverse
# => [3, 2, 1]

a
# => [1, 2, 3]

This version returns a new Array without mutating the old one, but the bang method?

a
# => [1, 2, 3]
a.reverse!
# => [3, 2, 1]
a
# => [3, 2, 1]

It mutates a. As an aside, Javascript's reverse totally mutates an Array, ask me sometime why I know...

The book mentions that sort and sort! behave similarly, but makes the lovely followup that methods like push, pop, delete, and shift also modify an Array too without a bang.

It mentions several methods may mutate things, so there's not always consistency here and it's best to be aware. Bang methods also tend to return nil in some cases when something does not change:

s = 'string'
s.gsub(/b/, 'c')
# => 'string'
s.gsub!(/b/, 'c')
# => nil

...meaning you can't chain things. They're faster, sure, but you trade a lot of what makes Ruby chaining so nice by doing so.

Rely on the Order of Your `Hash`es

In the next section it mentions something which can be very useful, but very different from other languages:

Hashes in Ruby retain insertion order.

That means running this code does this:

hey_its_ordered = { first: 'mama', second: 'papa', third: 'baby' }
hey_its_ordered.each { |entry| pp entry }
# [:first, 'mama']
# [:second, 'papa']
# [:third, 'baby']

...and adding one more element:

hey_its_ordered[:fourth] = 'grandma'

...puts it at the end. The book also mentions that changing an existing element does not reorder things.

This section hasn't really changed much if at all from Ruby 1.9, so there's not much to comment on here.

In the Wild

The book then goes into a few examples. The first examples are mainly covering class-methods which don't return an instance, but rather a collection. A few of those examples:

File.readlines('/etc/passwd')
object.public_methods
my_class.ancestors

Those types of methods tend to be common where Ruby will return a collection or other appropriate type, but the next example is a little clearer where generic collections really come in handy as a return type.

Let's take this XML:

<characters>
  <super-hero>
    <name>Spiderman</name>
    <origin>Radioactive Spider</origin>
  </super-hero>

  <super-hero>
    <name>Hulk</name>
    <origin>Gamma Rays</origin>
  </super-hero>

  <super-hero>
    <name>Reed Richards</name>
    <origin>Cosmic Rays</origin>
  </super-hero>
</characters>

If we were to parse that into Ruby we'd get something like this:

require 'xmlsimple'
data = XmlSimple.xml_in('dc.xml')

# Returns:
{
  "super-hero" => [{
    "name" => ["Spiderman"],
    "origin" => ["Radioactive Spider"]
  }, {
    "name" => ["Hulk"],
    "origin" => ["Gamma Rays"]
  }, {
    "name" => ["Reed"],
    "origin" => ["Cosmic Rays"]
  }]
}

It's really something just how much you can express with Hashes and Arrays in Ruby, and very frequently (and admittedly not always a great idea) I tend to avoid classes in favor of them until I get a tangible benefit from abstracting that data into a class wrapper.

Arrays and Hashes are simple to work with, have known interfaces, and don't require additional effort beyond language knowledge to use effectively.

Staying Out of Trouble

The book warns about manipulating a collection you're currently iterating on. In one case it's not a great idea to mutate state, but mutating the state of something that's currently in use like iteration? That's just asking for problems and errors.

Consider the book's example here:

array = [0, -10, -9, 5, 9]
array.each_index { |i| array.delete_at(i) if array[i] < 0 }
pp array
# => [0, -9, 5, 9]

It skips -9 because the element at that index just shifted with the deleted element.

The book then mentions making large Arrays inadvertently like so:

array = []
array[24601] = "Jean Valjean"

...being a reference to Les Miserables, but every element up to 24601 is now nil and that's not free in terms of memory.

The next example the book gets into is a unique list of words using a few different methods:

word_is_there = {}
words.each { |word| word_is_there[word] = true }

unique = []
words.each { |word| unique << word unless unique.include?(word) }

The second being much much slower as it has to iterate that unique list multiple times to find if a word is unique. Hashes have a lookup time of O(1), whereas Arrays are more of an O(n) lookup time.

While one can use the Hash case for this, Set is easier:

require 'set'
word_set = Set.new(words)

...or get into Enumerable and find the uniq method:

words.uniq

...which encapsulates the entire idea quite nicely without the extra work.

Wrapping Up

In Ruby chances are real high you're going to encounter collections, so knowing what they are and how they're used is a massive boost in your early productivity for both reading and writing.

Over the years Ruby has added a lot of Enumerable, Pattern Matching, and other features which make dealing with collections much easier. Later chapters will cover this, but that shouldn't stop you from taking a glance at a few in the docs.

The next chapter covers Strings, which will be the other most likely candidate for things you'll encounter and have to work with in Ruby.

Let's Read – Polished Ruby Programming – Ch 3.1 – Local Variables

Brandon Weaver — Mon, 30 Aug 2021 06:19:51 +0000

You can find the book here:

https://www.packtpub.com/product/polished-ruby-programming/9781801072724

With that said let's go ahead and get started.

Chapter 3 – Proper Variable Usage – Local Variables

The third chapter covers the following topics:

Using Ruby's favorite variable type – the local variable
- Increasing performance by adding local variables
- Avoiding unsafe optimizations
- Handling scope gate issues
- Naming considerations with local variables
Learning how best to use instance variables
- Increasing performance with instance variables
- Handling scope issues with instance variables
- Naming considerations for instance variables
Understanding how constants are just a type of variable
- Handling scope issues with constants
- Visibility differences between constants and class instance variables
- Naming considerations with constants
Replacing class variables
- Replacing class variables with constants
- Replacing class variables with class instance variables using the superclass lookup approach
- Replacing class variables with class instance variables using the copy to subclass approach
Avoiding global variables, most of the time

We'll be covering the first section on local variables to make this chapter's post more digestible.

Using Ruby's favorite variable type – the local variable

The chapter starts in by explaining local variables in Ruby, and mentions they're the only type without a sigil. For a quick list here are a few you might find later:

@variable - Instance variable
@@variable - Class variable (generally avoid)
$variable - Global variable (generally avoid)

We'll get into some of the issues with the latter two, as does the book, but for now we'll focus on local variables along with the book.

Increasing performance by adding local variables

Local variables are fast. The book mentions this, and most of the reason behind it comes from less indirection as previous chapters have mentioned. On the low level that means they're also more likely to be in the CPU cache.

The book opens with this code example:

time_filter = TimeFilter.new(
  Time.local(2020, 10),
  Time.local(2020, 11)
)

array_of_times.filter!(&time_filter)

Note - I dislike hanging indent, so I avoid it. You can read more into that here, but the short version is harder to maintain, longer diffs, and far harder to read with long-lines. Whitespace is free, use it.

Now the stated purpose of TimeFilter here is to return whether or not a Time is within the start and end of a range, but later sections here mention that if a beginning or ending is missing we'd likely want to treat it more like a begin-less range or an endless range.

Note - That's a partial hint that ranges can also be used to solve this problem, give it a try and see if you can figure that out as a challenge.

Speaking of unidirectional filtering, the book continues with this example:

after_now = TimeFilter.new(Time.now, nil)
in_future, in_past = array_of_times.partition(&after_now)

The idea being that partition can divide a list of times into ones occurring either in the future or in the past. Noted this is one reason so many harp on good variable names, as the ones used here make the intention more immediately clear for this code.

Editing Complaint: Now the next bit confuses me, and feels poorly edited in context with the rest of the text. It mentions that we could implement this as a method on Enumerable and goes into a bit about using a class as a Proc. I feel like a paragraph was cut out here, making it very confusing.

What I assume this was meaning to say was that one could patch a method into Enumerable to achieve a similar effect with time ranges, but a class that can be coerced into a Proc is more flexible and does not patch Ruby.

The TimeFilter Class

Moving past that, the book then goes on to show an implementation of the class:

class TimeFilter
  attr_reader :start, :finish

  def initialize(start, finish)
    @start = start
    @finish = finish
  end

  def to_proc
    proc do |value|
      next false if start && value < start
      next false if finish && value > finish

      true
    end
  end
end

The purpose of this section was to focus on optimizations that can be made to this implementation.

Note - Before we get into this, and the book does mention it later, these are micro optimizations. More often than not this is completely overkill for optimizing a program, and the actual issues are going to be much higher level. Prefer code that is first working, readable, and understandable before pursuing these and make sure you have evidence before optimizing at this small of a scale.

The first optimization is around the attr_reader methods getting called repeatedly in the to_proc method. To get around that the book mentions binding these to local variables instead to only hit those methods once:

def to_proc
  proc do |value|
    start = self.start
    finish = self.finish

    next false if start && value < start
    next false if finish && value > finish

    true
  end
end

The second optimization mentioned is variable hoisting, or moving those local variable bindings up above the Proc itself:

def to_proc
  start = self.start
  finish = self.finish

  proc do |value|
    next false if start && value < start
    next false if finish && value > finish

    true
  end
end

This particular technique works because of closures, as the book mentions, which you can read about more here. The short version is that functions in Ruby (Proc, block, lambda, etc) are closures, they remember the context they're created in, meaning they can access those variables.

The third optimizations mentioned are around limiting the scope of the function generated in the cases of a start or end date not being present:

def to_proc
  start = self.start
  finish = self.finish

  if start && finish
    proc { |value| value >= start && value <= finish }
  elsif start
    proc { |value| value >= start }
  elsif finish
    proc { |value| value <= finish }
  else
    proc { |value| true }
  end
end

Just for the sake of curiosity though let's run this through its paces:

Warming up --------------------------------------
          Original    66.000  i/100ms
             Local    72.000  i/100ms
     Hoisted Local    88.000  i/100ms
     Filtered Proc    98.000  i/100ms
    Filtered Range    83.000  i/100ms
Calculating -------------------------------------
          Original    655.049  (± 2.6%) i/s - 3.300k in 5.041153s
             Local    709.828  (± 3.9%) i/s - 3.600k in 5.080284s
     Hoisted Local    902.202  (± 2.9%) i/s - 4.576k in 5.076483s
     Filtered Proc    951.916  (± 3.0%) i/s - 4.802k in 5.049386s
    Filtered Range    825.598  (± 2.1%) i/s - 4.150k in 5.028796s

You can find the code here, but note that I've also added a range just to see what'd happen.

Constants Example

This section has one more example on replacing constants with locals, but as mentioned in the previous section this is the type of thing you only need if you're really grinding things down to exceptionally small optimizations:

num_arrays = 0
large_array.each do |value|
  if value.is_a?(Array)
    num_arrays += 1
  end
end

The first optimization is to hoist the Array constant:

num_arrays = 0
array_class = Array

large_array.each do |value|
  if value.is_a?(array_class)
    num_arrays += 1
  end
end

Which doesn't seem very common, but the book puts another more interesting example here:

large_array.reject! do |value|
  value / 2.0 >= ARGV[0].to_f
end

# Optimized
max = ARGV[0].to_f
large_array.reject! do |value|
  value / 2.0 >= max
end

...but then reminds us there are some mathematical optimizations:

max = ARGV[0].to_f * 2
large_array.reject! do |value|
  value >= max
end

Now personally, for me, unless I really really need to optimize things I'm going to avoid bang (!) methods and mutation in general sections, as very very rarely have I had performance intensive enough sections to justify this level of optimization, but it can be handy to know if you ever find yourself in such a situation.

Really though, so much of my Ruby knowledge ends up being "just in case" rather than immediately applicable, and quite often I question the necessity of memorizing all of it. That said, if you're maintaining OSS like Jeremy does this type of thing can have multiplicative benefits across a significant number of Ruby applications in the wild.

Context matters more than strong opinions on how things should be done.

Avoiding unsafe optimizations

What I really appreciate here on the book is it mentions some of the cases where you can have issues. It mentions idempotency, or avoiding side-effects with those local variables, and uses this example:

hash = some_value.to_hash

large_array.each do |value|
  hash[value] = true unless hash[:a]
end

...and the potential optimization:

hash = some_value.to_hash
a_value = hash[:a]

large_array.each do |value|
  hash[value] = true unless a_value
end

...and then the trap implementation which will fail:

hash = some_value.to_hash

unless a_value = hash[:a]
  large_array.each do |value|
    hash[value] = true
  end
end

The book mentions this as potentially dangerous as it assumes that the large_array does not contain an :a element or a default proc that deals with it. Personally I like the followup example with times a bit better:

enumerable_of_times.reject! do |time|
  time > Time.now
end

...and the flawed optimization:

now = Time.now

enumerable_of_times.reject! do |time|
  time > now
end

This one is quite a bit more complicated. Time.now is going to return a different time when called, introducing variance in the program. Perhaps you want that variance, perhaps not, so one does need to be aware of that. The book mentions cases in which the block yields at an interval slow enough to introduce substantial drift from the first call of Time.now, but even small drift can introduce all types of difficult bugs to track down.

The really concrete example which demonstrates the point of this area is if you have a proc checking whether a time is greater than now:

greater_than_now = proc do |time|
  time > Time.now
end

In this case the definition of now is very important to be immediately at calling time, rather than having an older reference, meaning optimizing like this will break things:

now = Time.now

greater_than_now = proc do |time|
  time > now
end

I really do appreciate that this book takes time to cover these cases instead of just going into optimizations directly.

Handling scope gate issues

Now this section can get a bit dense, and covers the visibility scope of local variables:

defined?(a) # nil

a = 1

defined?(a) # 'local-variable'

module M
  defined?(a) # nil

  a = 2

  defined?(a) # 'local-variable'

  class C
    defined?(a) # nil

    a = 3

    defined?(a) # 'local-variable'

    def m
      defined?(a) # nil

      a = 4

      defined?(a) # 'local-variable'
    end

    a # 3
  end

  a # 2
end

a # 1

That was one of the reasons they'd used a lambda function in the first chapter.

Editing Note - The book tends to switch between preferring Proc and Lambda, whereas it might be nicer to have some consistency there. Personally I prefer Lambda, but understand why proc might be preferred when referencing procs frequently. I still think that's a confusing choice in Ruby to have so many function types.

Naming considerations with local variables

The next section covers conventions in naming variables. The short version of what the book recommends is:

Use lower_case_ascii_snake_case for local variables, preferably in ASCII
Just because you can use emojis does not mean you should
Non-english languages can justify skipping ASCII, but may make it more difficult to work with
Careful on how long your names are

Jeremy is right on length, there's a fine line between is_a_long_phrase_like_this versus something like long_phrase. Personally if a variable is that long it may be a hint that the variable is doing too much contextually and needs to be factored out.

There are three examples used on name length:

# Using `a`, which is short for `album`
@albums.each do |a|
  puts a.name
end

# Using numbered params
@albums.each do
  puts _1.name
end

# Spelling out the full word
@albums.each do |album|
  puts album.name
end

As the book mentions a can be reasonably inferred from context, but that may be vague here:

array.each do |a|
  puts a.name
end

Spelling out album isn't that long, and may be justifiable, but the next example makes a point against spelling things out every time:

TransactionProcessingSystemReport.each do |transaction_processing_system_report|
  puts transaction_processing_system_report.name
end

Sure, it's accurate, but that's exhausting to read as the book mentions. It mentions a few abbreviations as alternatives here:

TransactionProcessingSystemReport.each do |tps_report|
  puts tps_report.name
end

TransactionProcessingSystemReport.each do |report|
  puts report.name
end

Neither of which, to me, lose much value by abbreviating the name in terms of clarity.

Now the book mentions something interesting: the longer the method or block the more names matter. Using a single-letter name in a long method means the original context is harder to see at a glance, adding a lot more value to longer names.

There are, however, some common conventions in Ruby and most programming languages at that on single-letter names like:

3.times do |i|
  type = AlbumType[i]
  puts type.name

  type.albums.each do |album|
    puts album.name
  end

  puts
end

i, j, k, and other such single-letters are going to be very familiar to a lot of C and Java programmers used to for loops. For integers this can make sense, especially as the book mentions for methods like Integer#times.

It also mentions Hash cases for key and value being k and v respectively:

options.each do |k, v|
  puts "#{k}: #{v.length}"
end

...but quickly follows with a common case which would be nested hashes and conventions around k2 and such:

options.each do |k, v|
  k.each do |k2|
    v.each do |v2|
      p [k2, v2]
    end
  end
end

For this particular case, as the book mentions, options isn't really a Hash, it's a collection of keys and values. That means that the typical Hash convention doesn't really make sense any more no? It suggests this instead:

options.each do |key_list, value_list|
  key_list.each do |key|
    value_list.each do |value|
      p [key, value]
    end
  end
end

Now this next part confuses me context wise, which involves gateless systems like define_method out of the blue. It mentions overwriting local variables unintentionally, but I believe this would have been better as its own section with a mention on the nuances of scoping, closures, shadowing, and related materials to give a broader overview. Scope gate does not feel as common a term to me, but I also come from a more functional background, so terms like closure are more familiar to me. Take with a grain of salt.

With that we're finished up the section on local variables.

The next section will cover instance variables.

DEV Community: Brandon Weaver

Ruby in FantasyLand: SumsUp

SumsUp

Struct vs Tagged

taggedSum vs SumsUp define

Lists with Sums

Wrap Up

Tales of the Autistic Developer – The Politician

The Politician

Defining the Term

The New Politician - Local Scope

The Problem

The Solution

The Strength

The Experienced Politician - Team Scope

The Problem

The Solution

The Strength

The Senior Politician - Team to Organization Scope

The Problem

The Solution

The Strength

The Staff Politician - Organization to Company Scope

The Problem

The Solution

The Strength

The Principal Politician - Company to Industry Scope

The Problem

The Solution

The Strength

Closing Thoughts

Tales of the Autistic Developer – Order and Chaos

Order and Chaos

A State of Chaos

A Contradictory Existence

Systems of Order

The Cost of Freedom

Superpower or Curse?

Closing Thoughts

Future of Ruby – AST Tooling

AST Tooling

Find and Replace

EmberJS Style Codemods

Babel Transpiler

A to B Inferred Transforms

Macros

Wrapping Up

Let's Read – Eloquent Ruby – Ch 6

Chapter 6. Use Symbols to Stand for Something

The Two Faces of Strings

Not Quite a String

Optimized to Stand for Something

In the Wild

Staying Out of Trouble

Wrapping Up

Let's Read – Eloquent Ruby – Ch 5

Chapter 5. Find the Right String with Regular Expressions

Introductory Examples

Matching One Character at a Time

Special Characters

Literal Characters

Combining Effects

Sets, Ranges, and Alternatives

Ranges

Common Set Shortcuts

Alternatives

The Regular Expression Star

Regular Expression Counts

Regular Expressions in Ruby

Equal Squiggly (=~)

Regex Flags

Methods Taking Regex

Beginnings and Ends

In the Wild

Staying Out of Trouble

Wrapping Up

Tales of the Autistic Developer - Loud Loud World

Loud Loud World

I Can Hear Everything

Smell Everything

Equal Squiggly (`=~`)

Instant `Array`s and `Hash`es from Method Calls

Rely on the Order of Your `Hash`es