Programming DSLs in Kotlin Design Expressive and Robust Special Purpose Code Venkat Subramaniam The Pragmatic Bookshelf Raleigh, North Carolina Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and The Pragmatic Programmers, LLC was aware of a trademark claim, the designations have been printed in initial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trade- marks of The Pragmatic Programmers, LLC. Every precaution was taken in the preparation of this book. However, the publisher assumes no responsibility for errors or omissions, or for damages that may result from the use of information (including program listings) contained herein. For our complete catalog of hands-on, practical, and Pragmatic content for software devel- opers, please visit https://pragprog.com. The team that produced this book includes: CEO: Dave Rankin COO: Janet Furlow Managing Editor: Tammy Coron Series Editor: Bruce A. Tate Indexing: Potomac Indexing, LLC Layout: Gilson Graphics Founders: Andy Hunt and Dave Thomas For sales, volume licensing, and support, please contact [email protected]. For international rights, please contact [email protected]. Copyright © 2021 The Pragmatic Programmers, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher. ISBN-13: 978-1-68050-793-5 Encoded using the finest acid-free high-entropy binary digits. Book version: P1.0—March 2021 Contents Acknowledgments . . . . . . . . . . . v Preface . . . . . . . . . . . . . . vii 1. Introduction . . . . . . . . . . . . . 1 Focus on the Key Characteristics 2 Kotlin as a Host Language 3 Steps to Program DSLs 3 2. Exploit Fluency . . . . . . . . . . . . 5 Remove Noisy Syntax 6 Design for Fluency 7 Make Syntax Obvious 9 Use Conventions to Improve Fluency 12 3. Get Domain Specific . . . . . . . . . . . 15 Use Domain-Specific Extension Functions 16 Create Extension Operators 17 Use Domain-Specific Operators 19 Use invoke to Remove Redundant Syntax 20 4. Provide Contexts . . . . . . . . . . . 23 Provide Context for Variables 24 Design for Separate Implicit Contexts 26 Use the Default Lambda Parameter Name for Context 29 Use Multiple Contexts to Remove Ambiguity 32 Use Inner Classes to Share State Between Contexts 34 5. Manage Scope and Handle Errors . . . . . . . 41 Leverage the Compiler 42 Leverage Type Checking 43 Restrict Scope of Functions 44 Contents • iv Control Scope with DslMarker 47 Proactively Handle Errors 50 6. Practice with Examples . . . . . . . . . . 53 Let’s Design a Builder 53 Devise Ways to Run DSLs from External Sources 57 Bibliography . . . . . . . . . . . . . 65 Acknowledgments We’re living in a rather unusual time, through a global pandemic combined with many regional issues. In hindsight, writing this book has given me a much needed reprieve, however temporary. The time spent on this book and interacting with Jackie, my editor, and the reviewers has been the high point of these months. I would like to start by thanking Andy Hunt and Dave Rankin of the Pragmatic Bookshelf for giving me this opportunity. Dave was incredibly supportive and helpful in the formation of this book. His constructive feedback through every step was very useful. Part of my motivation to write books is the opportunity to interact with Jackie, who, over time, has turned into a good friend. I admire her ability to put in such tireless efforts while dealing with many uncertainties of the current times. Thank you for spending time talking about the book and for motivating me when things appeared rather bleak. This book has evolved so much based on the extensive feedback by an amazing set of technical reviewers. They offered so many suggestions, corrected me where the details were not accurate, and motivated me to rework parts that needed significant improvements. My sincere thanks to Tom Adam, Vasile Boris, Hadi Hariri, James Harmon, Rebecca Parsons, Eugene Petrenko, Ian Roughley, William Rudenmalm, Ilya Ryzhenkov, Giordano Scalzo, Ken Sipe, and Bruce Tate. One benefit of releasing the book in beta is the opportunity to improve it using the feedback from early readers. I thank Graeme Collis and Curtis Riggs for helping me to fix errors. I thank my wife Kavitha for her support and letting me hide in the basement hours on end as I worked on this book. report erratum • discuss Preface Fluent, concise, expressive code, and low ceremony are some the traits of good domain-specific languages (DSLs). Creating a DSL is twice the joy—we can write elegant code, which in turn can help our domain experts work with ease and convenience. In this book you’ll learn how to design and implement your own DSLs using Kotlin. I’ve kept it really short so we can cut to the chase and get to imple- menting DSLs. Multiple examples will guide you through the essentials. Make sure to key in and execute each one of them to gain practice. Thank you for joining me on this journey. Who Is This Book For? This book assumes you are familiar with Kotlin and have some reasonable understanding of DSLs. It’s intended to quickly guide you through the steps necessary to build DSLs using Kotlin for JVM or Android applications. If you’re a programmer interested in using Kotlin to build DSLs, you picked the right book. You’ll also find this book useful if you’re a lead developer, architect, or a technical manager who is involved in the development of applications that make use of DSLs. You may also use this book to train your developers to become proficient with using Kotlin for programming DSLs. What’s in This Book? We’ve intentionally kept this book short to help you to quickly pick up key tips and tricks to create DSLs using Kotlin. This book will not serve as an introduction to Kotlin nor to DSLs, as it assumes some knowledge of both. For an introduction to Kotlin refer to Programming Kotlin [Sub19], and for an introduction to DSLs refer to Domain-Specific Languages [Fow10]. report erratum • discuss Preface • viii After a quick introduction of the steps to create DSLs with Kotlin, we’ll dive straight into each of the steps. We’ll first focus on making the syntax fluent by exploiting the flexibilities of Kotlin. Then we’ll look at ways to bring domain- specific vocabulary into your DSLs. Following that we’ll devise ways to bring multiple contexts into the execution environments. We’ll then walk through the steps to make DSLs robust and resilient. Finally, we’ll wrap with a few more examples of designing DSLs. Each step of the way, we’ll look at a number of code examples for you to practice along with. Take the time to key in each example, compile it, and execute it. Pause to make changes, break it, put it back together, try some variations, and then walk along to the next tip or trick to design your DSLs. Online Resources This book has an official page1 at the Pragmatic Bookshelf website. From there you can download all the example source code for the book. You can also provide feedback by submitting errata entries and join in the discussions on the forum. If you’re reading the book in PDF form, you can click on the link above a code listing to view or download the specific examples. Turn the page and let’s get started with programming DSLs in Kotlin. 1. http://www.pragprog.com/titles/vsdsl report erratum • discuss 1 CHAPTER Introduction Both in life and programming, it’s not just what we say but how we say it that matters. The “how” in domain-specific languages (DSLs) is intriguing. It elevates the task of designing DSLs into an art form, where we can focus on fluency, conciseness, and esthetics of the syntax without compromising the engineering concerns of semantics, correctness, completeness, robustness, and resilience. Design should be functional and serve its essential purpose. A good design is also easy, intuitive, convenient, and pleasant to use. Kotlin is a wonderful language that can meet those goals and, at the same time, reduce the effort it takes to implement DSLs. In this book, you’ll learn how to create your own DSLs in Kotlin that are easy and intuitive for the users. You’ll learn how to build fluency and how to extend the language so you can easily add domain-specific properties and functions. We’ll quickly move to the techniques of adding an execution context for the DSLs, so as to integrate the code in the DSL into the larger scope of the application in which they’re used. Finally, we’ll look at ways to make the code robust and handle errors, both ahead of execution and at runtime. Let’s start with an example of a DSL. The following Cascading Style Sheets (CSS) syntax is intriguing: a.active { color: #FF0000; } It’s simple, easy to both write and read, and we don’t have to be a programmer to work with it. Once we know the context and a few nuances of the syntax, we can be on our way to use CSS to tailor the appearances of websites. That’s a pretty darn good domain-specific language, albeit an external DSL. It’s report erratum • discuss