DEV Community: Marie K. Ekeberg

Become a Maven ninja!

Marie K. Ekeberg — Mon, 17 Oct 2022 16:43:34 +0000

Today we are going to look at some small tricks that will make you more effective when using Maven! Some of this will be simple, and some of them you might not have heard about. I've done some presentations at work and similar earlier about this, and there is almost always something new to people. The topics range from basic usage and flags, to ways of handling your dependencies. One or two might be a bit enterprise specific, but most can be useful no matter if you program inside a company or not. (no secret that I love those of you who, like myself, LOVE computers with a burning passion! <3 )

If you don't know, Maven is a build automation tool (dependency management, building, running tests etc.) used for languages on the JVM (Java Virtual Machine). I use it when programming in Kotlin and Java, with the latter becoming less and less frequent (Kotlin rules!!). Several people will probably ask why I'm not using Gradle instead, but that is a discussion for another time.

There is probably much more that could be covered, but I think this is the most important once you know the basics. If you are new to Maven, suggest starting with an introduction like this. The guide covers creating projects as well, but many modern frameworks have easier and better generators. Spring Boot have its own initializer website, and I've made a CLI version. Quarkus also have a nice web UI you can use to create new projects.

My last self-promotion before we begin... General command line skills can be very useful when working with almost any command line tool, including Maven. If you need a refresher, I recently wrote a guide to getting started with the command line (important topics: piping, searching with grep, less).

Basic usage and flags

Check Maven version

I want to show this for one reason, it's useful when checking for possible errors. Simply type mvn -v and you will get information about the Maven and Java versions currently being used:

(remember that the Java version can be changed by changing where the environment variable JAVA_HOME points to!)

package vs install

You may have noticed that you have a .m2-folder in your home directory. This can contain a settings.xml file (if you have specific local settings like proxies), as well as your local Maven repository (where Maven downloads and stores dependencies and artifacts locally). Why is this important? package builds your project (compiles, run tests etc.), and install does the same in addition to installing it (copying it) to your local Maven repository (.m2/repository).

NB! As package does not install to .m2 directory you can get some weird issues in multi-module Maven projects with dependencies to each other. Maven reads the dependencies from this local repository, and if it doesn't find it there, it will try the to download it.

using -f option to run a specific pom file

Just like the title says. If you do something like mvn -f mymodule/pom.xml install, Maven will build based upon the pom.xml file in the directory mymodule instead of the directory you are currently in.

using -X option to get debug information

mvn -X goals (replace goals with the actual Maven goals!) will show you looooots of information you can use when debugging possible issues. Just be aware that this is a lot of information! Ranging from all packages imported, what settings files are used (local for your user as well as global settings for the computer), complete configurations for things like Surefire (testing) and so on.

Now a little story time! I recently helped someone I know with some issues they were having with Maven. All dependencies (within an enterprise) timed out when downloading, and there was a note of a proxy we couldn't find in his local .m2/settings.xml file. How did we find the issue you may ask? Was it some global settings in a parent pom? Well, actually no! Within the first 100 lines of running mvn -X install we got our answer. A global settings file was put into Mavens install directory (probably by mistake and forgotten). By using the -X option we found the problem, without scratching our heads for days :)

Tests

Run single test(class)

You can run only tests with mvn test, but did you know you can run just a single test class by using mvn test -Dtest=MyClassTest? If you have several test classes with that name, use the fully qualified name (including package, example: com.example.MyClassTest).

Want to run just a single test method within that test class? Just as simple! mvn test -Dtest=MyClassTest#myMethod will run the test myMethod within your test class.

Don't trim stack trace

Sometimes you get unexpected nullpointers or other exceptions within the method you are testing. Some times you will se a very minimal stack trace with just your test method, and the rest cut off (aka trimmed). If you want the complete stack trace with causes, line numbers etc., then you can use the definition -DtrimStackTrace=false! (works with test, package install, other goals, etc.). Helps me a lot, especially since I prefer to use the command line instead of big bloaty IDEs.

Skipping tests

Want to skip all tests when building? mvn install -DskipTests will run install like usual, but not run any tests (but they will still be compiled!).

Dependency plugin

tree

mvn dependency:tree is one of the most useful commands for checking the dependencies in your project, including transitive dependencies (dependencies of your dependencies and so on). This include all versions of dependencies being used. These reports can be quite long for bigger projects, so it can be useful to pipe the result to less or search it using grep (if you have a suspicion of deprecated code and similar causing weird behavior).

analyze

Have a suspicion that you use conflicting versions of packages? Or have unused dependencies in your project? mvn dependency:analyze can help you here! It will print all info like this. (also useful to browse by piping the output to less!).

NB! Some dependencies in big frameworks like Spring might not be used directly at compile time, so there might be some false positives in the unused packages report.

display-ancestors

Many enterprises (and maybe open source projects) have hierarchies of parent pom files to handle global settings, approved dependency versions and so on. Sometimes you may want to see what version of parent poms you are currently using (maybe to debug if you are using the correct one, because these things can be updated!). Then mvn dependency:display-ancestors is your friend! Running it with a new Spring Boot project will show you the version of the Spring Boot starter poms it's using:

Versions

Maven have a versions plugin that can be used for several operations relating to versions. The only command here I find useful is mvn versions:set -DnewVersion=1.0.0. This will set the new versions of your project (including submodules) to 1.0.0. No need to edit the files manually! Neat!

Bonus: ZSH completion

Oh-My-ZSH has some really useful completions so you don't have to memorize any Maven commands. Just add mvn to your plugins list, open a new tab in your terminal (or new session) and you get nice completion! (you probably need Maven installed first, just to mention it...). Mine looks like this plugins=(git z gh mvn thefuck) on my personal machine (kubectl is also super useful if you use Kubernetes!).

Let's do an example. Let's say I type mvn dependency: and press tab. Then ZSH will suggest the possible completions for me:

(you can off course complete anything, including goals like package, deploy etc. I just wanted to show something that didn't cover my entire window ;) )

One thing worth mentioning is that this plugin completes the Spring Boot goals like mvn spring-boot:run and Quarkus goals like quarkus:dev as well! How cool is that?!?

The awesomeness of pattern matching in Rust

Marie K. Ekeberg — Thu, 13 Oct 2022 15:43:27 +0000

If you have followed me for a while, you know that I have really started enjoying Rust in the last year. Rust have many great features, and pattern matching is one of them. If you have used other languages like Haskell or Standard ML, you will notice some similarities. Same with the complete basic pattern matching with when in Kotlin (with some minor work). The pattern matching in Rust makes for expressive, readable and clear code. I admit that the Rust way of doing it is my personal favorite. In this article we will take a look at this topic, and maybe you will see why I think it's so great!

Basics of patterns

Refutable vs irrefutable

Patterns in Rust come in two types; refutable and irrefutable. Patterns that match conditionally are called refutable, while patterns that match any possible value are called irrefutable. Which one you can use will depend on the context. For example, a let-statement will need a irrefutable pattern, because what would happen if a variable in a let-statement doesn't get a value?

  // Irrefutable patterns
  let x = 2;
  let (x, y) = (2, 3);


  // WILL NOT COMPILE
  // let does not allow refutable patterns
  let Ok(x) = someString.parse::<i32>()
  // trying to parse a string will return a Result, and can not guarantee that a result and not an Err is returned

if let-statements on the other hand can have refutable patterns, as the body is evaluated conditionally:

  if let Ok(x) = someString.parse::<i32>() {
      // ... do something if someString can be parsed as a 32 bit integer ...
  }

  // if let can have a refutable pattern, so we can also use a value for x:
  if let Ok(64) = someString.parse::<i32>() {
      // ... do something if someString can be parsed as a 32 bit integer ...
  }

We will see more examples of these kinds of statements and patterns below. If you still think the topic of "refutable vs irrefutable" is hard, reread this section after reading the rest of the article. The Rust documentation also has some examples and explanations that can be worth it to check out.

Destructuring

Many patterns are patterns that destructure various types, and they can also be mixed and match together. Let's look at some of them.

Tuples

We already saw example of tuple destructuring in the last section, but let's take another look:

  // myTuple is of type (i32, i32, &str)
  let my_tuple = (1, 2, "hellothere");
  let (x, y, my_str) = my_tuple;

Here we see in the last line that my_tuple is destructured into 3 new variables: x, y, and my_str. This can be done for all sorts of tuples, as long as the destructured types match.

You can also match elements with .. (possibly multiple) or _ (single), which are often used to skip elements:

  // ignore my_str
  let (x, y, _) = my_tuple;

  // ignore everything after x
  let (x, ..) = my_tuple;


  // bigger tuple
  let bigger_tuple = (1, 2, 3, 4, 5);

  // get first and last
  let (first, .., last) = bigger_tuple;

  // ambiguous! NOT ALLOWED
  // How would the compiler even know which element you wanted
  let (.., middle, ..) = bigger_tuple;

(notice that the patterns have to be unambiguous)

You might try the first tuple example above with a tuple struct and get an error message. That is because tuple structs have more in common with struct destructuring, so they require special syntax:

    // Defining a tuple struct that looks like the tuple in the previous example:
    struct MyTuple(i32, i32, String);


    // Destructure it
    let my_tuple = TupleStr(1, 2, "hellothere".to_string());
    let TupleStr(x, y, my_str) = my_tuple;

(notice that we had to change our &str type to String, as the compiler can't infer the size of any &str we might want to use in our tuple struct. Strings are saved on the heap, so that solves that problem).

Tuple structs are technically structs, which brings us to our next type of destructuring...

Structs

Structs are not that much different, and an example might show it clearly:

  // define a simple struct
  struct Point {
      x: f32,
      y: f32,
      z: f32
  }

  // create a variable to use
  let myPoint = Point {
      x: 1.0,
      y: 0.5,
      z: -1.0
  };

  // destructure it!
  let Point { x, y, z} = my_point;

  // Maybe we just want x and y?
  let Point { x, y, .. } = my_point;

  // or maybe just z
  let Point { z, .. } = my_point;

One thing you should notice when destructuring structs is that the name have to match the one found in the struct, and that .. have to come last. .. in this case simply means match the rest and ignore the result.

Enums

The simplest case for an enum is simply to match one with no data:

  // define a simple enum
  enum Color {
      Red,
      Blue,
      Green
  }

  // match if our color is green
  if let Color::Green = my_color {
      // .. do something is color is green ..
  }

This is not that interesting, as Rust enums are way more powerful. If you are not familiar with them, they can contain data! Let us see an example:

  // More advanced enum
  enum HttpRequest {
      Get,
      Post(String)
  }

  // match the post request
  if let HttpRequest::Post(data) = my_request {
      // .. do something with the post request data ...
  }

  // can also ignore data
  if let HttpRequest::Post(_) = my_request {
      // .. do something when post request ...
  }

If an enum has several arguments, you can do most of what you are used to from tuples above. You can use ranges (e.g, 1..=2), or skip some elements with .. by itself (e.g, MyEnum(firstElem, .., lastElem)).

Combined

You can also combine all of the above into your own patterns! Structs inside enums, enums inside tuples etc. The list goes on!

  // Define some nested structure
  enum Color {
      Red,
      Blue,
      Green
  }

  // imagine old OpenGL from the early 2000s where colors of points were interpolated across the shape
  struct Point {
      x: f32,
      y: f32,
      z: f32,
      color: Color
  }

  struct Triangle(Point, Point, Point);


  // A destructuring based upon the data we want
  // gvet only x for the first point when the first points color is blue
  if let Triangle(
      Point {
          x,
          color: Color::Blue, ..
      },
      ..,
  ) = my_triangle {
      // .. do something with the data we wanted for some reason ..
  }

Other patterns

There are other types of patterns as well, and these are mostly used with match which you will see more of below. The first one is the or-matcher:

  // matches 1, 2 or 3
  1 | 2 | 3

  // Matches one of the strings
  "first" | "second"

We saw ranges briefly above:

  // matches 1 to 10 (inclusive)
  1..=10

  // matches 1 to 10 (non-inclusive)
  1..10

(ranges can also be used as indexes for arrays to fetch multiple elements)

The last pattern I want to show is one used for testing and capturing values. Yes, you can have both! This functionality is often used for capturing values somewhere inside a pattern that satisfy a given condition, and can be used deep inside the pattern. Let us see an example with ranges:

  // Integer version of point
  struct MyData {
      x: i32,
      y: i32,
      z: i32,
  }

  // Match data x value when it's between 1 and 20 (inclusive)
  if let MyData {
      x: my_x @ 1..=20, ..
  } = my_data
  {
      // .. do something with the my_x that is 1<=20 ..
  }

(notice that the variable we use is now called my_x)

These can be used with if-let and other places that allow refutable patterns, but is mostly used together with other patterns in match. I have rarely, if ever used any of these with if-let (maybe with the exception of ranges).

That should be the most important topics, but there might be things I've missed. Rust is an evolving language after all, and new features may have been added. There might also be features I don't use as much, and therefore forget about. You can see the Rust documentation on this topic for more.

Caveats

One minor caveat I have found is that Rust is finicky about floating points in patterns. Not about the capturing part, but if you try to use them in ranges and so on. It warns you that it is not supported. We all know how floating points behave, and that they are very sensitive to different scales and that they are rarely (if ever) exact. That probably explains why they are not recommended to use with more advanced Rust patterns.

Where to use pattern matching? (example time!)

We have already seen some basic examples above, but let's dive a bit deeper and see how and where to use pattern matching. We have already seen lots of let and if-let statements, so let's look at match and patterns in function signatures!

match

This is in my view the switch/case statement you are used to in other languages, but on steroids! match lets you write crazy powerful matchers. We have already looked at all the different patterns above, so let us have some quick examples:

  // A more extensive version of httprequest
  enum HttpRequest {
      Get,
      Post(String),
      Put(String),
      Custom,
      Unknown
  }

  // a match expression
  match my_request {
      Get => {
          // .. do something with get ..
      }
      Post(data) | Put(data) => {
          // .. do something with the data ..
      }
      _ => {}
  }

(matches have to be exhaustive, and cover all cases. You see we handle this with the wildcard _ above. This is also an advantage, as the compiler helps you remember all cases!)

match also have another clever thingy called a match guard! It is basically an extra if-sentence inside a case. Let's add it to the second case above:

   match my_request {
       HttpRequest::Get => {
           // .. do something with get ..
       }
       HttpRequest::Post(data) | HttpRequest::Put(data) if !data.is_empty() => {
           // .. do something with the data ..
       }
       _ => {}
   };

Here we have added a check to see if the string data sent in is not empty! Pretty nifty!

functions

You can use patterns in function definitions! That is really cool, right? You do have to remember that the patterns have to be irrefutable like for let. Don't be sad yet! It still means you can use a lot of destructuring operations we have seen above! Let's look at some examples:

  // test data
  struct Vector2d {
      x: f32,
      y: f32
  }

  // destructured Vector2d
  fn length(Vector2d { x, y }: Vector2d) -> f32 {
      (x.powi(2) + y.powi(2)).sqrt()
  }

  fn x_val(Vector2d { x, .. }: Vector2d) -> f32 {
      x
  }

They can be deep as well if you want to, but remember to not f**k up your code's readability.

Feel free to share any clever pattern matchings you have done in your function signatures in the comments! And yes, I know you have them in JavaScript as well.

Now you have hopefully seen a little bit of what patterns in Rust can do. If you are new to Rust, maybe it has inspired you to learn the language? :)

Debugging GameBoy Advance (GBA) programs/games in Emacs

Marie K. Ekeberg — Tue, 11 Oct 2022 15:45:40 +0000

There are not many articles on debugging GameBoy Advance C code around the web, and most of them seem to be about debugging in VSCode. While VSCode is good, it is far from the awesomness that is Emacs! Debugging GBA code with Emacs is far easier than you would think, and in this article I wills how you how.

If you have not heard about GDB before, I suggest quickly refreshing the basics so you don't get confused each time I mention it below :)

You may already have found some resources related to VSCode around, like this repository and this article. The launch.json files could be adapter to work with dap-launch (more on that later), but would require some manual work because of several smaller issues (one of them being that Emacs does not support VSCode tasks.json files at the moment). Both of them also seem to require you to copy-paste the launch.json files, and edit them with corrected paths each time (see how you can avoid that in Emacs at the end!).

Basic GBA debug workflow (editor independent)

No matter which editor you debug in, the workflow is about the same. You will need DevkitPro gba-dev and an emulator like mGBA. If you want to familiarize yourself with some C code for GBA, as well as Makefiles with CFlags and other build options, there is an example repo you can check out :)

The process is as follows:

Compile with debug symbols (-g in DevkitARM gcc). This will generate two files: an elf-file executable with debug symbols, and a standard gba-file (a "normal" executable for GBA which you can also put on any flash card like the EZFlash).
Start your emulator with gdb debug process. Your emulator will show the visuals here, and will be interacted with using gdb. The best modern emulator in my view is mGBA, where we start the debug process with mGBA --gdb myfile.gba.
Attach to the gdb debug process with DevkitARMs gdb executable using the elf-file.

You could just do it like this without any editor, but your debugging will then happen in the command line, and you will have to remember gdbs commands. This is not as tedious as it sounds, but many of us prefer to see the breakpoints happening, as well as the state, directly in our editors. Many editors therefore provide either a gdb interface, or can interact with it using a debug adapter. You can use debug adapters in VSCode through various plugins, in Emacs with dap-mode, in Vim with Vimspector, and probably in other editors as well. What is written here should be transferable to other editors.

The above approach should in theory work for both C (and C++) and assembly code, though I have only tried it for C.

Adapting it to Emacs with dap-mode

We will use dap-mode with the dap-gdb-lldb option here. Under the hood, it uses the debug adapter from the Native Debug VSCode extension. Configuring it is described on the dap-mode webpages. After we have configured dap-mode, we could in theory reuse the launch.json configurations from the VSCode related articles above. That will require that you also use lsp-mode, as dap-launch depends on the lsp-workspace-root function and will not resolve when lsp-mode is not used. I don't use lsp-mode with C (company-clang and company-c-headers provide what I need), so the next logical solution would be to create a debug template ourselves:

  (dap-register-debug-template "GBA debug"
                               (list :name "GBA debug"
                                     :type "gdbserver"
                                     :request "attach"
                                     :gdbpath "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gdb"
                                     :target ":2345"
                                     :cwd "/path/to/dir"
                                     :executable "file.elf"))

Configure cwd and executable to your projects needs, which can also be done by creating one template and configuring it with dap-edit-debug-template. You will off course first need to compile and run your emulator with a gdb process.

No matter which way you start a debug process, it will look about like this with dap-mode and mgba:

(here I have added a few breakpoints, which you can toggle with M-x dap-breakpoint-toggle)

Simplifying with gba-debug.el

The solutions above entails some manual work, and that lead me to automate it. Wouldn't it be nice to just run one simple command, and then everything compiles and your debug process just automatically begin? That's exactly what I was thinking, so I created a simple Emacs extension. If you use a Makefile to build, and configure the path to mGBA and DevkitARMs gdb, you can debug a GBA program directly with M-x gba-debug-program. No need to compile manually, run mGBA manually or anything else!

Emacs Lisp debugging tips

Marie K. Ekeberg — Mon, 10 Oct 2022 16:56:05 +0000

Have you ever gotten weird errors in an Emacs Lisp package? Something like "wrong type argument" or similar shown in the minibuffer? At first glance, these seem kind of cryptic. Where do they come from? Can I get a stack trace? What arguments are functions called with? Today I will show you how to answer these questions!

Show stack traces

You have probably gotten one of those weird "wrong type argument" errors, or similar errors just printed in the minibuffer before. You have probably also navigated to the *Messages*-buffer to check if there is any additional information. Did you know you can see a stack trace instead? Then you can see the functions being called leading up to the error!

There are several ways to activate it. The most common way is to just set Emacs to enter the debugger when an error happen. You can do this by setting the variable debug-on-error
to true (either in your config or just executing it right in your scratch buffer):

  (setq debug-on-error t)

I usually prefer to turn it on by need using M-x instead, M-x toggle-debug-on-error.

Let's show a quick example using a function from the lsp-mode codebase. Experienced programmers will probably notice the issue right away, but let's see how we will debug it. We are going to assume that we have gotten a hash table that we want to fetch results from called result-data. Running it in the scratch buffer will always show a stack trace, so let's make an interactive function we will call using M-x:

  (defun my-lsp-mode-fun ()
    (interactive)
    (let* ((my-key "key")
           (my-data (lsp-get result-data my-key)))
      ;; ... do something with the data ...
      ))

If we call it without turning on debug-on-error, we will see the error Wrong type argument: symbolp, "key" in the minibuffer and messages-buffer. Some of you will probably already see that it expects a symbol, not a string. It will be even more clear if you turn on debug-on-error and running it again:

  Debugger entered--Lisp error: (wrong-type-argument symbolp "key")
    symbol-name("key")
    lsp-keyword->string("key")
    lsp-get(#<hash-table equal 0/65 0x47fa6ca9> "key")
    (let* ((my-key "key") (my-data (lsp-get result-data my-key))))
    my-lsp-mode-fun()
    funcall-interactively(my-lsp-mode-fun)
    call-interactively(my-lsp-mode-fun record nil)
    command-execute(my-lsp-mode-fun record)
    helm-M-x-execute-command(my-lsp-mode-fun)
    helm-execute-selection-action-1()
    helm-execute-selection-action()
    helm-internal((((name . "Emacs Commands history") ...truncated....
    helm-M-x(nil)
    funcall-interactively(helm-M-x nil)
    call-interactively(helm-M-x nil nil)
    command-execute(helm-M-x)

(some data are truncated for better readability by me)

You see that we get a stack trace of all operations that is done by Emacs. Even if you are not making packages yourself, this can prove very useful to provide information in issue trackers when reporting issues (e.g, on the packages Github repo).

There are several other ways to toggle errors, ranging from message patterns to signals. You can read more about that on the documentation pages.

Tracing function invocations

Another useful troubleshooting tips to know is tracing function invocations/calls. Sometimes we just want to see what arguments a specific function is called with, and be notified about it each time it is run. This is done with the =trace-function= command (M-x trace-function, followed by the name of the function you want to trace).

Let's reuse the code example from above and trace lsp-get. After calling our interactive function once, we will then see a buffer called *trace-output* with data like this:

  ======================================================================
  1 -> (lsp-get #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data ()) "key")
  1 <- lsp-get: !non-local\ exit!

Calling it more times will populate the buffer with more data. You can trace as many functions as you want. When you are done tracing a function, you can call untrace-function and choose the function you want to stop tracing.

I find this super useful when developing packages. When calling a function external to your package (i.e, from another package or built-in to Emacs Lisp), it's very useful to be able to trace how functions behave. This includes when, or if, they are called, as well as with what arguments.

Packages that make Emacs Lisp more pleasant

Marie K. Ekeberg — Mon, 10 Oct 2022 16:33:39 +0000

Emacs Lisp can sometimes seem a little archaic compared to more modern languages. In higher level language we are spoiled with a multitude of easy string handling, list handling, pattern matching and so on. What if I told you that some packages can give you the same ease of use for Emacs Lisp? That they provide more clear APIs, give features you are used to from other languages, and/or abstract away the more tedious details.

We will mainly look at 3 packages: s.el, f.el and dash.el. Two of these packages (first and last) are maintained by Magnar Sveen, who are also known for Emacs Rocks and What The .emacs.d (which are still great resources for learning and finding inspiration for your Emacs configuration!). We will also look at ht.el. These packages are used a lot in many of the Emacs packages you use in a day to day basis, like lsp-mode and rustic just to name a few. As most of these already have tons of examples in their READMEs, my main goal of this article is to inspire you to check them out. Hopefully you will know of one new package after reading this article :)

s.el

s.el has a simple mission: to provide more pleasant string handling, and it touts itself as "The long lost Emacs string manipulation library". If you have worked with strings in Emacs Lisp without s.el, it can be a bit tedious. Some functions work like you expect with string inputs, while others expect a list of strings (e.g, string-join). Others have completely different prefixes (e.g, concat).

Let's look at some examples of operations from s.el:

  ;; Test if input is a number
  (s-numeric? "123")
  ;; => t

  (s-numeric? "ab34")
  ;; => nil


  ;; Get the first or last n characters of a string
  (s-left 4 "This is a test")
  ;; => "This"

  (s-right 4 "This is a test")
  ;; => "test"


  ;; Transform to (lower) camel case
  (s-lower-camel-case "square function")
  ;; => "squareFunction"

There is a ton more examples in the github repo for s.el, so I suggest you check it out if you find it interesting! :) Some of the functions are now provided in newer versions of Emacs (with the string--prefix like string-pad-right and string-pad-left), but there are still some operation that Emacs does not provide (e.g, s-left and s-right to get the first or last n characters in a string respectively).

f.el

Yes, you read that right: f.el! f.el provides many functions for handling files and directories, including paths and content. While it is certainly possible to do some of these operations directly in standard Emacs Lisp, it takes quite a lot more instructions than the simple ones provided by f. f makes it way more readable, and makes the intent more clear.

  ;; Get the filename of the file (or inner directory)
  (f-filename "/home/someuser/Programming/Rust/mos/Cargo.toml")
  ;; => "Cargo.toml"


  ;; Create a directory
  (f-mkdir "Programming" "Emacs")
  ;; Makes the directories Programming/Emacs


  ;; Test if input has a file extension
  (f-ext-p "/test/test")
  ;; => nil

  (f-ext-p "Cargo.toml")
  ;; => t

Like for the other packages, f.el provides many examples of usage in its readme.

dash.el

If you have ever read source code for any of the Emacs packages you use, you may have noticed operations like -let, -map, -lambda, ->, and similar ones all starting with a dash. These are from dash.el, and provides quite a lot of nice syntax! Ranging from improved usage and pattern matching (if let expressions like in Rust is available!), to Lisp constructs often found in other languages (like the threading operator ->). Clojure is probably the biggest inspiration, and this package makes list operations as pleasant as they are in Clojure! (LISP stands for LISt Processing after all!). If you have coded in Emacs Lisp for a while, you may have used †he various cl-functions (e.g, cl-map), but with dash you get more clear and pleasant APIs to do the same and more.

  ;; Flatten a list
  (-flatten '((1 2 (3 4))))
  ;; => (1 2 3 4)


  ;; Pattern matched let
  ;; (my-hash-table is a hash table with keys "name" and "age")
  (-let [(&hash "name" name "age" age) my-hash-table]
    (message "Hi %s who is %d years old!" name age))
  ;; with an example hash table with name=Nils, and age=56, this will print:
  ;; "Hi Nils who is 56 years old!"

  ;; There are even pattern matched lambda! -lambda


  ;; Thread through the chain using the first argument as the last argument in the next function call etc.
  (->> '((1 2) 3)
      (-flatten)
      (message "My list: %S"))
  ;; prints:
  ;; "My list: (1 2 3)"

I LOOOOVE the pattern matching in dash! The -let variant in dash is probably the functionality in this article I use the most. Threading is also something that can be really nice, and I should probably use it more in places where I usually collect results with let and let*.

ht.el

ht.el is a library for managing hash tables. While this can be done with the standard library, ht.el makes the intent more clear. They have also written a bit about the why in their readme. Like they mention, more consistent naming, common prefixes and more, makes coding in Emacs Lisp more pleasant. It's easy to sometimes forget the name of a function, and a common prefix makes it easier to find when using auto completion.

  ;; Create a new hash table
  (let ((my-hash-table (ht ("key" "val")
                           ("other key" "other val"))))
    ;; add another key
    (ht-set! my-hash-table "EmacsLisp" "More awesome with these libraries!")

    ;; return the value with the key "MyKey", or "Not found :(" if not found
    (ht-get my-hash-table "MyKey" "Not found :("))

There are also many more utility functions, like accessing nested hash tables, copying hash tables, getting the size and more! Like usual, there are more examples in the readme :)

Creating container images with Ansible (using ansible-bender)

Marie K. Ekeberg — Tue, 05 Apr 2022 18:06:12 +0000

Did you know that you can use Ansible to make container images? It's actually a very readable way to create images compared to some Dockerfiles you find online (if you don't think so, you have probably never read one that is 100+ lines). In this article we will look at building images using ansible-bender, which makes for a good way to make images with Ansible with minimal fuzz.

Need a refresher on Ansible? It was introduced in the last article, so feel free to read it to refresh the concepts (at themkat.net). You probably won't get much use out of ansible-bender without knowing the basics of Ansible first.

In the last article, building container images with Ansible was briefly discussed. An external blog article on that very subject was linked to, and if you read it you may have seen a lot of manual steps using Docker- and Buildah-commands. This seems like a lot of boiler plate code just to make container images with Ansible, right? From that idea, ansible-bender was born! Ansible-Bender uses Buildah to build your images, and Podman to handle them (some commands like pushing images, build logs, inspecting images etc. are included into Ansible-Bender). Buildah is a container image builder that does not depend on any external programs, and can build containers for any container runtime. A very big downside is that it's only supported on GNU/Linux-based systems, which is bad news if you are using Mac OS X (or god forbid if you are one of the Windows users, ugh). To combat this issue I made a Docker image that includes Buildah and all dependencies, that can be used to run Ansible-Bender on other platforms. Might be a bit slower than just using it on a GNU/Linux-based system, but beats not being able to use it at all!

There are obviously some pros and cons relating to using such a tool compared to plain Dockerfiles:

Pros:

Can be way more readable than some Dockerfiles you find around the net. Ansible is beautiful to read, so this is a pretty big benefit in my view. Not hating on Dockerfiles, as I think those are fun to write as well. They just get tedious to write if they get too big.
Already using Ansible playbooks to build your infrastructure? Then you can consider using those, or parts of those, to write containers.
Imported roles, playbooks etc. can be tested for correct behaviour using tools like Molecule.
Imported roles, playbooks etc. from Ansible Galaxy can make building images way faster (depending on the type of image you make off course).

Cons:

Base images NEEDS to have Python installed. You can do this during runs by turning off gather_facts and installing it during playbook run.
Some rough edges, especially with the caching mechanism. Most problems solved by using --no-cache if they occur. Not really a show stopper, as those issues can be fixed by contributors in the future. If you feel like you have what it takes, that could maybe be you? :)

In the end, it comes down to taste. If you really love Ansible and its expressiveness, I think you will enjoy using ansible-bender.

Using ansible-bender

So you have installed ansible-bender, either directly or by using an image like mine above. What's next? If you have installed Buildah and Podman as well, you can actually start using the tool directly! If you want a playbook with ansible-bender specific variables inserted for you, you can use the ansible-bender init command, and a playbook.yml file is created for you. In essence, that is what an ansible-bender playbook really is; a normal Ansible playbook with some special variables. Those special variables are covered in depth in the documentation.

You may wonder: what if I have ansible_bender variables in more than one play, what happens then? Only the variables from the first play is used. Beyond that you are free to have multiple plays.

Talk is cheap, let's look at some examples!

Example: Containerized Emacs setup

Continuing the trend from the last article! (note: last article on themkat.net) Let's set up an image with my Emacs setup ready to be used.

---
- name: Emacs setup - Containerized 
  hosts: all

  vars:
    ansible_bender:
      base_image: python:3.9-slim-bullseye

      target_image:
        name: myemacs
        cmd: bash
        user: themkat
        working_dir: /home/themkat

  pre_tasks:
    - name: Update package archives (Debian-based)
      apt:
        update_cache: true
        cache_valid_time: 7200
      when: ansible_os_family == "Debian"

  tasks:
    - name: Make sure Emacs and git is installed
      package: 
        name:
          - emacs
          - git
        state: present

    - name: Create themkat user
      user:
        name: themkat
        create_home: true
        state: present

    # had issues with using the home symbol + become_user here. Might be an issue to look out for
    - name: Download Emacs  config
      #become_user: themkat
      git:
        repo: https://github.com/themkat/.emacs.d.git
        dest: /home/themkat/.emacs.d

    - name: Make themkat the owner
      file:
        path: /home/themkat/.emacs.d
        owner: themkat
        recurse: true
        state: directory

NOTE: As you see in the comment above, I have experienced some minor issues with the become_user and home symbol/tilde. These might be bugs in ansible-bender or relating to containers. Have not tested enough to find the culprit yet, so presenting this as something to be aware of.

How do we build this? Use the command ansible-bender build playbook.yml. You might wonder why we have the "when Debian"-check when it will always be Debian with that base image. The reason is simple: by doing this we keep the setup flexible. If we wanted a Fedora image, we could simple override it from the command line ansible-bender build playbook.yml fedora:35.

As you can see above, the differences from a plain Ansible playbook to a ansible-bender one used to create images are not that big. Simple some image related variables like the base image, as well as resulting image name, command to be run, user etc. Standard settings we do when making container images in general.

Example: Simple Spring Boot application image

Let's do something slightly different by demonstrating the usage of volumes and Ansible roles during build. It's not unusual to want to package an application into a container, and for simplicity we put it into the same directory as the playbook itself (so we can use the playbook_dir variable). To not make this example too advanced, we simply use a Spring Boot application made from Spring Initializr without any changes (if you prefer a terminal UI, there is one for that too). We'll use geerlingguys java role to setup Java to not boggle down the example with Java setup.

---
- name: Containerized Spring Boot app
  hosts: all
  vars:
    ansible_bender:
      base_image: fedora:35
      target_image:
        cmd: java -jar /app/spring-app.jar
        name: spring-app-example
      working_container:
        volumes:
        - "{{ playbook_dir }}:/src"

  roles:
    - role: geerlingguy.java
      java_packages:
        - java-11-openjdk

  tasks:
  - name: Make app directory that will include our application
    file:
      path: /app
      state: directory

  - name: Build application
    command:
      chdir: /src
      cmd: ./mvnw clean install
      creates: /src/target/spring-app-0.0.1-SNAPSHOT.jar

  - name: Copy jar file to app directory
    copy:
      remote_src: true
      src: /src/target/spring-app-0.0.1-SNAPSHOT.jar
      dest: /app/spring-app.jar

To run this one, we will have to use ansible-galaxy to install geerlingguy.java first, either with a requirements file or directly (ansible-galaxy install geerlingguy.java). After that we can simply build our image like in the last example.

What happens here? We build our Maven Spring Boot project, and put the resulting jar file into a app-directory. You may wonder: Shouldn't we delete the contents of src? Won't all the source code and build files be included in the final image? No! When building is done, src is unmounted and the directory is empty. Pretty neat!

Useful commands

ansible-bender has quite a few useful commands beyond just building images. If you want to fetch earlier build logs, that can be done. Inspecting images is simple. But to me, the most useful is probably pushing images. Not necessarily to a central repository or something, but to Docker. I have to admit, I still use Docker. Let's say we have built the myemacs image as in the first example, and want to push it to our docker daemon with the tag 0.1. Then we simply run:

  ansible-bender push docker-daemon:myemacs:0.1

Summary

In summary, ansible-bender seems like a promising tool that definitely have some fun and useful use cases. Making images with Ansible seems like a very readable way to make images, especially for bigger ones. Dockerfiles quickly gets messy, and Ansible might be an antidote for that issue.

Bit tricks - Absolute value without branching

Marie K. Ekeberg — Thu, 17 Feb 2022 19:18:04 +0000

Bit trickery is always interesting! Sometimes you can use them to avoid branching (like if-checks), other times they are useful to save a few CPU cycles to avoid expensive operations. The absolute value trick I will show you here, is mostly to avoid branching. Why would you want to avoid branching? Many newer processors, from the mid 90s and onward, do something called pipelining to achieve a form of instruction level parallelism. While a classic processor fetch an instruction, decode it, then execute, a pipelined processor can fetch the next instruction while the previous one is decoded. You can have multiple operations like this almost in parallel. If we have to branch, like for an if-check, we might not have fetched the correct next instruction anymore, and might have to fetch new ones (for the whole pipeline). This can be an expensive operation. Calculating absolute values is a problem where we often have to have a branch (an if-check for smaller than 0).

It should be noted that modern computers like the X86, modern phones, modern ARM processors (like the ones in M1 Macs) etc. have branch prediction and are very fast. This makes bit trickery like the ones in this article unnecessary, and it will have little to no effect. The same is true for the Java Virtual Machine (JVM) which already does a lot of optimizations for you.

Hopefully you remember what the absolute value is. It is simply a positive representation of the value, in other words it's the value without its sign. -10 will be 10, and 10 will still be 10. Mathematically we can define it like this:

\begin{equation} |x| = \begin{cases} x & \text{if } x \geq 0 \\ -x & \text{if } x < 0 \end{cases} \end{equation}

Naive implementation with branching

We can implement the mathematical formula above directly:

  int absoluteValue(int input) {
    if(input < 0) {
      return -input;
    }
    else {
      return input;
    }
  }

(we could also have used the ternary operator above, but decided to use a plain if for clarity)

The implementation explains itself. Now onto the clever trick!

The bit trick

For integers, the trick can be described like this:

  int absoluteValue(int input) {
    int mask = input >> 31;
    return (input ^ mask) - mask;
  }

(can be done inline if you prefer to. Useful if you want to avoid the stack page for the function call. You might have a clever compiler already doing this for you though...)

Note! If you are compiling for multiple processors, with different bit sizes for int, you can use sizeof to calculate the byte-size of int and use the result to calculate the bit shift length (remember to subtract 1 from the total size!).

But wait... How does it work? First of all, let's note that we work with signed integers here, which means that the bit shift preserves the sign bit (0 for positive, 1 for negative).

Let's see what happens for a positive number (and also 0):

Mask becomes 0 (sign bit is propagated down to the lowest bit place)
Input XOR 0 becomes the input itself.
The input minus 0, is still the input itself.

Now let's take a negative number:

Mask becomes -1 (bit shift 31 places. Sign bit propagated, so the new empty places to the left is filled with the sign bit 1). This is the same as 1111 1111 1111 1111 1111 1111 1111 1111 for the integer above. (Read up on two complement and how negative numbers are handled if this seems foreign to you).
Input XOR -1 becomes the (bit-)negated version of the input (the same as using the NOT operator on the input)
The result of the previous operation minus -1, which is the same as adding 1, becomes the same as multiplying the input variable by -1. Remember that negated value + 1 is how we get the negative version of our current number in the two complement system.

You might now see the pattern here. For positive numbers (and 0), nothing happens, we just return the input number. For negative numbers, we negate them and add 1, which is the same as creating the negative version of our number in the two complement system.

If that still sounds like magic to you, let's break it down further! You can probably skip these sections if you understand the trick already.

(Bit) Negation if negative number

All bits in the mask will either be 0 or 1, so let's take a look at a XOR table for a single mask bit:

A	B	Result
0	0	0
1	0	1
0	1	1
1	1	0

Let's say B is the mask in this case. Take a close look. For 0 mask, the input (A) stays the same, while for the 1 mask it is negated! (in other words: imagine using the NOT operator on A only when B is 1).

Two complement

We can easily see that for a positive number, we get the same number back (positive number XOR 0 - 0 is still the same number). What happens for negative ones? The number is first negated, then we subtract negative one. Wait a minute... This is the same as negating and then adding one! Which is how we negate a number in the two complement system. This is how negative numbers are represented. That's the magic of this trick :)

Where can this be useful?

While not super useful for modern high powered hardware, it might be useful in other contexts. Some of these are low power microcontrollers, retro computers and retro console programming. Some processors in these sort of devices are low powered, and sometimes we might need some clever tricks. The absolute value trick might prove useful where we simply want to avoid the extra cycles the jump call and conditional require, even though it shines the brightest in cases of pipelined processors.

Spring Boot - Easy customizations for your applications!

Marie K. Ekeberg — Sat, 29 Jan 2022 12:55:55 +0000

In this article I will show you two types of easy customizations you can do with your Spring Boot applications. One of them can be very useful, and one is mostly cosmetic for the benefit of those seeing the server logs. This article is language agnostic, so it can be used for all programming languages you might make Spring Boot applications in (probably Java or Kotlin).

Custom banner

When you start your Spring Boot application you will see a banner like this:

This is pretty standard, and maybe a bit boring. Did you know that you can create your own? Just create a banner.txt file in your src/main/resources directory, and it will show at startup! Those of you who want to do more advanced colors, formatting, showing versions etc. might wonder how that is done? There are several variables for that, some are documented in a great way in this Github Gist I found. Other formatting includes AnsiColor and AnsiStyle (links are for the enums found in the current version of Spring Boot). Using a collection of these and some ascii art (generated by this website) we can create a cool banner for our very cool server:

  ${AnsiColor.GREEN} ________  ________  ________  ___               ________  _______   ________  ___      ___ _______   ________     
  |\   ____\|\   __  \|\   __  \|\  \             |\   ____\|\  ___ \ |\   __  \|\  \    /  /|\  ___ \ |\   __  \    
  \ \  \___|\ \  \|\  \ \  \|\  \ \  \            \ \  \___|\ \   __/|\ \  \|\  \ \  \  /  / | \   __/|\ \  \|\  \   
   \ \  \    \ \  \\\  \ \  \\\  \ \  \            \ \_____  \ \  \_|/_\ \   _  _\ \  \/  / / \ \  \_|/_\ \   _  _\  
    \ \  \____\ \  \\\  \ \  \\\  \ \  \____        \|____|\  \ \  \_|\ \ \  \\  \\ \    / /   \ \  \_|\ \ \  \\  \| 
     \ \_______\ \_______\ \_______\ \_______\        ____\_\  \ \_______\ \__\\ _\\ \__/ /     \ \_______\ \__\\ _\ 
      \|_______|\|_______|\|_______|\|_______|       |\_________\|_______|\|__|\|__|\|__|/       \|_______|\|__|\|__|
                                                     \|_________|                                                    

                                        ${AnsiStyle.BOLD}${AnsiColor.RED}- Spring Boot Version ${spring-boot.formatted-version} -${AnsiStyle.NORMAL}
  ${AnsiColor.DEFAULT}

Here we see some of the codes in action! So how might this look? Like this:

If you are the more boring type, you can also remove the banner with a yaml property:

    spring:
      main:
        show_banner: false

Static web pages

Now time for the most known feature in this article: hosting static webpages with Spring Boot. You may or may not know that files found in src/main/resources/static are hosted as webpages when running your application? This means you can make an index.html file that is served when accessing the root path of your server in the browser. Try making one, and run mvn spring-boot:run (if you use Maven), and you can access it at localhost:8080 (unless a different URL is configured). To show you an example, here is an index.html file:

  <html>
      <head>
          <title>My awesome little website!</title>
      </head>
      <body>
          <h1>Welcome to this awesome server!</h1>
          <br />
          <a href="#">Documentation</a>
      </body>
  </html>

Then we can open the browser, and voila!

What are these websites useful for? Other than being fun to have, off course. Some ideas for information you might want to show:

Maybe you have some documentation that the user of your server might want to read? Swagger pages, SOAP WSDL files, API documentation for possible integration code, link to relevant web pages to get people up to speed with relevant concepts etc.
URLs of other APIs your servers communicate with, unless they should be masked (some more proprietary solutions still do this). Most applications don't like in a vacuum anymore, and you might use different URLs in test vs production (which you will see fast if shown on a site like this).
Build information like versions, user who last committed changes etc.
Spring Boot Actuator link (these are sometimes configured to be other places than the default)
Spring Boot Actuator calls to provide information directly in the site (might require some JavaScript). Monitoring etc.

So they are not just for the developers having fun, they can provide real value as well!

You can also provide your own error web pages, with the most famous example being 404 errors. This is as easy as what we did above, with one simple tweak: The sites need to be in the error-subdirectory (inside your src/main/resources/static directory). So your 404 page would be at this path src/main/resources/static/error/404.html.

If you want to make more advanced web pages, this can be done with something like Thymeleaf (templating system), JSP, or just with some JavaScript code. You would probably want to have something like stylesheets and other files included to make your sites more fancy as well. The site above was kept simple for the sake of example (and for you to have something to copy-paste to test quickly if you want to!).

I focused on more general tips that applies to most Spring Applications in this article. There are off course more customizations (that are more dependent on your problem domain) that can be done, including custom Actuator endpoints and custom FailureAnalyzer (when application fails to start), but these are topics for a separate article.

Do you have any other fun customizations for Spring Boot? Feel free to mention them in the comments!

Often forgotten features in Kotlin

Marie K. Ekeberg — Fri, 28 Jan 2022 19:28:16 +0000

This time we will look at features in Kotlin that are often overlooked in walktroughs or other places, but are still cool and can be useful! Some are features some of us might know of, but often forget exist. Others are features we forget exist untill we see them mentioned, probably because we don't use them as often (or very rarely). Hopefully you will see at least one feature you have forgotten existed!

Inline objects

The most known usage of inline/anonymous objects in Kotlin is in places where we need to send in an object (in the Java sense of the word) that implements an interface, the particular object is only needed once in your code, and a lambda won't suffice (because the interface is not functional, i.e, it has several methods). That was probably a bit confusing if you haven't seen it before. It's hard finding good examples of this, as it doesn't happen that often (probably happens more often on Android with its click handlers and more). Let us just use Runnable as a quick example, even though you could easily have used a lambda:

  val myThread = Thread(object : Runnable {
      override fun run() {
          println("Using an anonymous inner class/object")
      }
  })

Now you may ask: how is this a forgotten feature? It's not like seeing this is rare! You are right, that's why I started this section with "the most known usage of...". Now to the feature we often forget is possible. You can actually create variables that are just objects, almost just like you are used to in JavaScript!

      val myObj = object {
          val name = "somename"
          val pair = getRandomPoint()
          val somelist = listOf("Element", "Another element")
      }

      println(myObj.name)
      println(myObj.pair)
      println(myObj.somelist)

You can also have functions, but if you don't implement an interface, those methods won't be visible outside the object. The exceptions to this rules are the methods you find in the Any class, which you can also override inside the inline/anonymous object (e.g, toString). There are a few other limitations as well. One particular, frustrating one, was that I could not destructure the pair above, and access the elements:

  val myObj = object {
      val (x,y) = getRandomPoint()
  }

  // NOT ALLOWED! :( 
  println(myObj.x)
  println(myObj.y)

This may be fixed in future versions of Kotlin. You also can't use inline objects at the top level in a file, and they have to be used inside a function or class. (at least from my experience in scripts using KScript).

Now you may ask: Where is this last feature useful? It might be useful as return values in private methods of classes, or as working storage for variables to group them. I think in general we should avoid this for bigger projects, as it may hinder readability a bit as the project grows. For scripts in Kotlin on the other hand, I think it can prove useful to keep the code concise and create logical groupings. That is where I see the biggest use for it.

tailrec

Let's start with the simplest recursive implementation of factorial:

  fun factorial(n : Int) : Int {
      if(n <= 0) {
          return 1
      }

      return n*factorial(n-1)
  }

Remember that every time a recursive call is done, a new stack page is created with the values of the variables (here the new value of n) which consumes more memory. In the above implementation, we see that there will be many such new stack pages depending on the value of n. We also need to backtrack once the recursive calls have finished (i.e, reached the base case in the if-check) and calculate the multiplications.

How can we improve? With the concept of tail recursion. What is tail recursion? Tail recursion is a compiler optimization (or in other languages like Scheme, interpreter optimization) that is done to reuse the stack page each time, and avoid the backtracking needed by classic recursive functions. When these conditions are met, you don't get a recursive process anymore, but an iterative one (just like for regular loops). Sounds awesome right? You will NEED to write your functions in a way that they don't need backtracking for this to work, so a lot of the responsibility is on YOU! After you have written your function in such a way, you can use the tailrec keyword. One way of implementing factorial this way is by using a optional argument with a default value (maybe write in docs how this works, especially if it is meant to be used by others!):

    tailrec fun factorial(n : Int, sum : Int = 1) : Int {
        if(n <= 0) {
            return sum
        }

        return factorial(n-1, sum*n)
    }

This is only one possible way, and you can probably find some better ways of solving this.

You may wonder; what happens if I use the tailrec keyword without meeting the condition above, in that the last call is a tail call (i.e, no backtracking needed). You will get a compiler warning saying that the recursive call is not a tail call, simple as that :)

Extension functions to lambdas

Lambdas are instances of classes behind the scenes, which means that you can create extension functions on them! If you never thought about it, this may seem confusing. What would the class name look like? Let's create one type of lambda (taking in two integers, and returning a new integer), and then later creating an extension function for it. First a simple add function:

  val add : (Int,Int) -> (Int) = { num1,num2 ->
      num1 + num2
  }

Take a close look at the type of the add-function. That is the class we can create extension functions for! Let's create a new extension function that returns the same function, but the execution will start with a simple print statement:

  fun ((Int,Int) -> (Int)).logged() : ((Int,Int) -> (Int)) {
      return { num1,num2 ->
          println("Calling function ${this.toString()}")
          this(num1,num2)
      }
  }

Now we can see it in use:

var addLogged = add.logged()
println("2+3 = ${addLogged(2,3)}")

As you can guess, the output will be:

  Calling function (kotlin.Int, kotlin.Int) -> kotlin.Int
  2+3 = 5

This was a very simple example, and there are more fun things you can do with this functionality. Maybe you want to create a memoized version of your function? Or create compositions of functions (e.g, create a =f(g(x))= function for two functions f and g)? Look around, especially in the realm of functional programming, and you might find more interesting use cases.

Delegation of properties/variables

Recap of delegation in classes

Most people know of the class-level delegation, but in case you don't, let's do a very quick recap. When extending a class or implementing an interface, the relationship is of type "is a" (e.g, a Toyota is a Car, a Siberian Husky is a Dog etc.). Composition, storing the relationship in a variable, is of the type "has a" (e.g, Manager manages/has a programmer do work for them, Cat has a human which gives them food etc.). Delegation is a special case of composition where we delegate work to another class. You probably don't want your Cat to implement the Human interface just to be able to get Food...? You want to delegate the work to the cats servant/owner. How do this look in Kotlin?

  interface Human {
      // usually the implementation would be implementation specific
      fun getFood() {
          println("Getting food")
      }
  }
  // implementations that in the real world probably implements their own getFood
  class GrownUp : Human

  class Cat(val name : String, servant : Human) : Human by servant


  // usage
  val me = GrownUp()
  val myCat = Cat("Mittens", me)
  myCat.getFood()

This looks just like the Cat implements the Human interface, but behind the scenes it delegates the work to a Human. That is the power of delegation for classes, and why it is often called a special form of composition (as the usage is a bit different then basic composition).

NB! Just to make it clear. The example above is very simple to illustrate the point. If you still feel unsure about it and want to see more examples, I suggest looking into the official documentation. This was only meant as a recap to prepare you for the main point, so I assumed you just needed a refresher :)

properties/variables

The delegation example above was probably familiar to you, as it is presented clearly in many Kotlin texts. Did you know that you can use delegates on properties/variables as well? This is a simple way of adding some extra functionality around the given type. Let's say you want a variable with a number, but it can only be even. Or a string that can only be lower case. Let's see how a stupid example like that can be implemented:

  // Even number
  class EvenNumber(private var num : Int) {
      operator fun getValue(thisRef : Any?, prop : KProperty<*>) : Int {
          return num
      }

      operator fun setValue(thisRef: Any?, prop : KProperty<*>, newValue : Int) {
          if(newValue % 2 == 0) {
              num = newValue
          } else {
              num = newValue - 1
          }
      }
  }

  var evenNum : Int by EvenNumber(23)
  println(evenNum)
  evenNum = 11
  println(evenNum)
  evenNum = 2
  println(evenNum)

  // string always lower case
  class LowerCaseString(private var str : String) {
      operator fun getValue(thisRef : Any?, prop : KProperty<*>) : String {
          return str
      }

      operator fun setValue(thisRef: Any?, prop : KProperty<*>, newValue : String) {
          str = newValue.lowercase()
      }
  }

  var myStr : String by LowerCaseString("Hello there")
  println(myStr)
  myStr = "hi"
  println(myStr)
  myStr = "MY HANDS ARE TYPING WORDS"
  println(myStr)

You may notice that the delegates don't need to implement an interface, but they still need to implement the above methods (values/vals probably don't need the setter).

Now let us see what the output looks like:

  23
  10
  2
  Hello there
  hi
  my hands are typing words

NB! You may notice that the setValue is not invoked on the constructor, which is something I want you to be cautious of. If you want to enforce it at that point, I would suggest using a explicit constructor or a init-block.

These examples are a little bit stupid on purpose, but they show some simple validation use cases for delegates. Now that you know how they work, you can probably think of more fun stuff to use it for :)

Honorable mention

Referential equality using ===

Let's say you have implemented the equals method, and it checks for structural equality (e.g, the fields are equal to each other). What if you want to check that they are the same object, do we need to remove the equals-method? NO! You can use === instead, and you check if the objects are the same objects in memory (i.e, same reference).