Building Internal DSLs in Your Favorite Programming Language
Software isn’t just about solving problems — it’s about making solutions expressive and readable. One powerful way to do this is by building Internal DSLs (Domain-Specific Languages).
If you’ve ever wished your code could read more like English (or your team’s own domain language), then an internal DSL might be the tool you’re looking for.
What Are Internal DSLs?
An Internal DSL is a mini-language built inside a general-purpose programming language.
Instead of creating a brand-new compiler or parser, you use your existing language’s syntax, features, and runtime to express domain logic in a more natural way.
Think of it as customizing your language for your project’s needs without leaving the language ecosystem.
Internal DSLs vs. External DSLs
It’s easy to confuse between them:
- External DSLs → standalone languages (e.g., SQL, HTML) with their own parser.
- Internal DSLs → embedded within another language (e.g., a Ruby RSpec test reads like plain English).
Internal DSLs are faster to implement because you don’t reinvent the wheel — you leverage the host language.
Why Build an Internal DSL?
- Improved readability — Code speaks the language of the domain.
- Fewer mistakes — Constraints baked into the syntax reduce errors.
- Faster onboarding — New developers learn the DSL instead of the whole codebase first.
- Reusability — The same DSL can be applied across multiple projects.
Internal DSLs
As opposed to external DSLs, which have their own independent syntax, An internal DSL (Domain-Specific Language) is a type of DSL that is embedded within a general-purpose programming language and utilizes the host language’s syntax and constructs. In other words, it’s not a separate language but rather a specific way of using the main language to achieve the benefits of DSLs with an independent syntax. The code written in an internal DSL looks and feels like regular code in the host language but is structured and designed to address a particular problem domain more intuitively and efficiently.
To compare the two approaches, let’s see how the same task can be accomplished with an external and an internal DSL. Imagine that you have two database tables, Customer and Country, and each Customer entry has a reference to the country the customer lives in. The task is to query the database and find the country where the majority of customers live. The external DSL you’re going to use is SQL; the internal one is provided by the Exposed framework (https://github.com/JetBrains/Exposed), which is a Kotlin framework for database access.
Here’s a comparison of the two approaches:
External DSL (SQL):
SELECT Country.name, COUNT(Customer.id)
FROM Country
JOIN Customer
ON Country.id = Customer.country_id
GROUP BY Country.name
ORDER BY COUNT(Customer.id) DESC
LIMIT 1Internal DSL (Kotlin with Exposed):
(Country join Customer)
.slice(Country.name, Count(Customer.id))
.selectAll()
.groupBy(Country.name)
.orderBy(Count(Customer.id), isAsc = false)
.limit(1)As you can see, the internal DSL version in Kotlin closely resembles regular Kotlin code, and the operations like slice, selectAll, groupBy, and orderBy are just regular Kotlin methods provided by the Exposed framework. The query is expressed using these methods, making it easier to read and write than the SQL version. Additionally, the results of the query are directly delivered as native Kotlin objects, eliminating the need to manually convert data from SQL query result sets to Kotlin objects.
The internal DSL approach provides the advantages of DSLs, such as improved readability and expressiveness for the specific domain, while leveraging the familiarity and power of the host language. This combination makes the code more maintainable, less error-prone and allows domain experts to work more effectively without the need to learn a completely separate syntax.
A Kotlin HTML Builder DSL
Kotlin’s syntax is well-suited for DSLs:
html {
head {
title { +"My Page" }
}
body {
h1 { +"Hello World" }
p { +"This is my internal DSL example." }
}
}Why this works well:
- Extension functions make the code feel like part of the language.
- Lambda with receiver allows nesting that mirrors HTML structure.
Common Pitfalls
- Overcomplication — If your DSL is harder to learn than the original language, it fails its purpose.
- Poor documentation — DSLs still need guides and examples.
- Leaky abstractions — Avoid exposing too much of the host language if it breaks immersion.
Picking the Right Language
Some languages are more DSL-friendly due to flexible syntax and operator overloading:
- Ruby — Very popular for DSLs (e.g., Rails migrations).
- Scala — Strong type system + functional features.
- Kotlin — Extension functions + lambda with receiver make DSLs clean.
- Python — Simple syntax and dynamic typing make it easy to prototype.
- JavaScript — Template literals and functional style work well.
That said — you can build an internal DSL in almost any language.
Real-World Examples of Internal DSLs
- RSpec (Ruby) — Readable test cases.
- Gradle Kotlin DSL — Build scripts that feel native in Kotlin.
- Jinja Filters in Python — Embedded in templates but powered by Python.
Conclusion
Building Internal DSLs is about making code read like conversation — clear, concise, and tuned to the domain.
Whether you’re writing tests, building configs, or defining workflows, a well-crafted DSL can cut cognitive load and boost productivity.
Start small, test ideas, and grow your DSL as your team uses it. Before long, you might find that the DSL becomes one of the most beloved parts of your codebase.
