The Power of Go Tools (John Arundel) (z-library.sk, 1lib.sk, z-lib.sk)

📄 File Format: PDF

💾 File Size: 3.6 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

(This page has no text content)

📄 Page 2

The Power of Go: Tools 2024 edition John Arundel Bitfield Consulting September 5, 2023 © 2023 John Arundel

📄 Page 3

The Power of Go: Tools Praise for ‘The Power of Go: Tools’ Introduction Who is this book for? What should I know before reading it? What version of Go does it cover? Where to find the code examples What you’ll learn 1. Packages The universal library Packages are a force multiplier The universal Go library is huge Sharing our code benefits us all Writing packages, not programs Command-line tools Zen mountaineering Guided by tests Building a hello package The structure of a test Tests are bug detectors So when should a test fail? Where does fmt.Println print to? Meet bytes.Buffer, an off-the-shelf io.Writer Failure standards Implementing hello, guided by tests We start with a failing test Creating a module One folder, one package A null implementation The real implementation The naming of tests Refactoring to use our new package

📄 Page 4

Going further 2. Paperwork Making our package more flexible Mandatory arguments are annoying What if we allow users to pass nil? Maybe some global variable instead? A struct is the answer A convenience wrapper with defaults A simple line counter Focus on behaviour, not implementation One possible first version What about configuration? Config structs don’t solve the problem An elegant option API Okay, so what’s an “option”? Options are functions “Always valid” fields Some internal paperwork Handling internal errors A line counter with options Methodical options Going further 3. Arguments Designing the behaviour Deciding the scope Testing CLI arguments A first attempt Test data files Creating the test data Using the data in a test The failing test Implementing file-reading Empty slice checking Testing the “no args” behaviour Closing files and other resources Updating the user interface

📄 Page 5

Some user testing Setting exit status Test scripts Running the program as a binary Introducing testscript Invoking test scripts Defining custom commands The delegate Main function The stdout assertion Testing arguments Going further 4. Flags Commands The Unix way Multiple main packages A words command A test for word counting Updating the test scripts Flags Introducing flags Adding a -lines flag Implementing the behaviour Help and usage information Going further 5. Files Writing to files The art of judicious logging Testing a WriteToFile function Designing errors out of existence Looking for inspiration What are we really testing? The go-cmp module Implementing a WriteToFile function File permissions When the directory doesn’t exist A disastrous bug

📄 Page 6

Using t.TempDir Finishing the job It’s clobbering time Ensuring permissions What’s the worst that could happen? A security leak Going further 6. Filesystems Files and filesystems What even is a file? Organising files A simple file finder Handling folders recursively Filesystems and io/fs Matching files by name Walking the tree A file-finding tree-walker Starting at the top The fs.FS abstraction Any path-value map is a “filesystem” The fstest.MapFS filesystem Adding a filesystem to our API Timing potentially slow operations Writing benchmark functions Taking fs.FS makes APIs more flexible Going further 7. Commands The exec package What even is a process? Managing command output When not to use exec When to use exec Migrating from shell scripts to Go Why use Go to run commands? A command wrapper in Go The pmset command

📄 Page 7

What can we test? Breaking down behaviour into chunks Parsing command output Testing the parsing function Parsing command output Clarifying the problem Writing a regular expression Using the regexp Integration tests Why isolate integration tests? Build tags Testing the command runner Running the command Capturing output When to import a third-party package Going further 8. Shells A simple shell Defining some behaviour Identifying the first test Comparing the incomparable Parsing user input Prototyping A pseudocode outline Main-driven development Feedback from user testing A stateful shell session What would we like to write? What object would make sense? Designing the Session object Running a session Testing the Run method Dependencies on external commands A dry-run mode Implementing Run What’s still missing

📄 Page 8

Globbing Redirection Piping Quoting Going further 9. Pipelines A realistic operations task Matching and counting log lines A quick shell spell Solving the problem with Go In what language would this be easy? Programs as pipelines A fluent API Errors in sequenced operations An error-safe writer Putting the pieces together How does data flow from one method to another? Testing the end of the pipeline Breaking ground Getting the test passing Adding error safety Obviousness-oriented programming Trying it out Hello, world The world strikes back Setting defaults with a constructor Reading data from files Another pipeline explosion Filtering data Extracting columns A String sink Testing Column Validating arguments Implementing Column The script package Was this a waste of time?

📄 Page 9

Introducing script Some simple one-liners More sophisticated programs Concurrent pipeline stages Custom filter functions Solving problems The landscape of simple programs Going further 10. Data Marshalling Serialisation The gob package A file-based data store Testing data persistence Setters and getters A sensible key-value API Testing the key-value machinery Implementing the store Adding persistence What are we really testing here? An end-to-end persistence test Saving and loading Tightening up the tests JSON: a text data format The json package JSON is a useful auxiliary language A JSON output option Adding JSON to the battery package Producing JSON strings What could go wrong? Testing ToJSON Implementing ToJSON Pretty-printing with indentation Querying JSON output YAML: a less verbose JSON Parsing YAML in Go

📄 Page 10

Designing the API with a test Defining our types The go-yaml package Decoding When unmarshalling doesn’t work The format of struct tags Setting defaults Eliminating config structs Going further 11. Clients A simple weather client What do we need? Kicking the tyres Environmental credentials Making a GET request Initial user testing A second pass Parsing JSON responses Testing ParseResponse To decode or to unmarshal? A temporary struct type The response struct Implementing ParseResponse What could go wrong? Other kinds of invalid data What are we really testing here? Back to a running program Constructing the request URL A FormatURL function Getting the location as input Refactoring the remaining code A paperwork-reducing GetWeather function Testing against a local HTTP server A simple httptest example A trustful TLS client A weather client object

📄 Page 11

A familiar pattern Refactoring the tests to use our client Writing the client constructor Refactoring GetWeather as a client method Testing GetWeather Implementing GetWeather A convenience wrapper Adding a Main function Adding temperature support Parsing temperature data More user testing Handling quantities with units Presenting temperatures in Celsius Defining a Temperature type Tackling more complex APIs Request data “CRUD” methods Last words Going further About this book Who wrote this? Feedback Mailing list For the Love of Go The Power of Go: Tests Know Go: Generics Further reading Video course Credits Acknowledgements A sneak preview 1. Programming with confidence Self-testing code The adventure begins Verifying the test Running tests with go test

📄 Page 12

Using cmp.Diff to compare results New behaviour? New test. Test cases Adding cases one at a time Quelling a panic Refactoring Well, that was easy Sounds good, now what?

📄 Page 13

Praise for ‘The Power of Go: Tools’ Curse you for derailing my day with another fascinating book! The content is absolutely awesome. —Peter Nunn Superb and well written: all the examples worked and were very helpful. —Lee Gibson It’s fantastic! I really like the approach. —Sal DiStefano The book does a great job of teaching what to do with Go. I really liked the emphasis on testing. —Pedro Sandoval Exactly the book I was looking for next! I love it. —Elliot Thomas What I really love about this book is it takes the newbie to the next level via real-world, relatable examples. The narrative flow clicks with me. —Rajaseelan Ganeswaran It’s clear, concise, and practical, especially for folks like me who enjoy the art of making end-user tools with Go. It’s really made me think when I write code about how simple and easy I can make it for folks to use, without, as John likes to say, ‘a lot of paperwork’. —Josh Feierman

📄 Page 14

Everywhere I go, I’m asked if I think the university stifles writers. My opinion is that they don’t stifle enough of them. —Flannery O’Connor

📄 Page 15

Introduction The guiding motto in the life of every natural philosopher should be, “Seek simplicity and distrust it.” —Alfred North Whitehead, “The Concept of Nature” Hello, and welcome to the book! It’s great to have you here.

📄 Page 16

Who is this book for? There are lots of books that will teach you Go, but not many that will show you what to do with it. In other words, once you’ve learned how to write Go code, what code should you write? This book is aimed at those who have a little experience with Go (or even a lot), and would now like to learn how to build good software with it. What is “good” software anyway? What would it look like in Go? And how do we get there from here? If software engineering is a craft, which it surely is, then how do we go about mastering it? It’s all very well to say “just write programs”, but how? How do we take some problem and start designing a program to solve it? How can we incorporate tests into the design? What are we even aiming to do here? I hope you’ll find at least some useful answers to these questions in this book, which focuses on developing command-line tools, but most of it applies to any kind of Go program. What should I know before reading it? While you don’t need to be a confident or expert Go programmer, I’ll assume in this book that you’re familiar with at least the basics: compiling and running Go programs, how structs and slices work, what functions do, and so on. If you’re entirely new to Go, or even to programming in general, I recommend you read my previous book, “For the Love of Go”, first:

📄 Page 17

Once you’ve read it, you’ll be in the ideal place to start reading this book. Go ahead! I’ll wait right here until you come back. What version of Go does it cover? This book uses Go 1.21, released in August 2023, and all the code samples have been tested against at least that version. However, Go puts a strong emphasis on backward compatibility, so all the code in this book will still work perfectly well with later Go 1.x versions. In general it should also work well with earlier versions, though I recommend you use the latest version of Go you can. If Go 1.21 isn’t yet available as a package in your operating system distribution, you can build it from source

📄 Page 18

or download a suitable binary package from the Go website directly: https://go.dev/learn/ Where to find the code examples There are dozens of challenges for you to solve throughout the book, each designed to help you test your understanding of the concepts you’ve just learned. Throughout the book, you’ll see a number of code goals for you to achieve, marked with the word GOAL, like this: GOAL: Get the test passing. When you see this, stop reading at that point and see if you can figure out how to solve the problem. You can try to write the code and check it against the tests, or just think about what you would do. If you reckon you have the answer, or alternatively if you’ve got a bit stuck and aren’t sure what to do, you can then read on for a HINT, or read on even further for step-by-step instructions on how to construct the SOLUTION. If you run into trouble, or just want to check your code, each challenge is accompanied by a complete sample solution, with tests. All these solutions are also available in a public GitHub repo here: https://github.com/bitfield/tpg-tools2 Each listing in the book is accompanied by a name and number (for example, listing hello/1), and you’ll find the

📄 Page 19

solution to that exercise in the corresponding folder of the repo. What you’ll learn By reading through this book and completing the exercises, you’ll learn: How to build reusable packages instead of one-off programs How to design user-friendly APIs and packages, without annoying paperwork How to write robust, testable tools that take command- line flags and arguments How to design Go packages that work with files and other kinds of streaming data How to write flexible tools to operate on trees of files, and more generally path-value databases such as URLs or zip archives How to use Go to drive external commands and provide elegant APIs to abstract their functionality How to write commands that interact extensively with users, such as shells How to sequence operations into simple pipelines that abstract away the details of handling streaming data and errors How to encode and decode data in binary format, and translate Go data to and from JSON and YAML formats

📄 Page 20

How to create robust, reusable client packages for HTTP services and other APIs