From 4cdfdb8f97d48f6e0a9ea5e93f097ad9a0531191 Mon Sep 17 00:00:00 2001
From:  <>
Date: Sun, 3 Mar 2024 13:09:02 +0000
Subject: [PATCH] Deployed bbcc32c4 with MkDocs version: 1.5.3

---
 clojure-cli/built-in-commands/index.html |  10 +++++-----
 search/search_index.json                 |   2 +-
 sitemap.xml.gz                           | Bin 3161 -> 3161 bytes
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/clojure-cli/built-in-commands/index.html b/clojure-cli/built-in-commands/index.html
index e9074372f..9855d06ae 100644
--- a/clojure-cli/built-in-commands/index.html
+++ b/clojure-cli/built-in-commands/index.html
@@ -877,9 +877,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#deps-tool" class="md-nav__link">
+  <a href="#deps-alias" class="md-nav__link">
     <span class="md-ellipsis">
-      :deps tool
+      :deps alias
     </span>
   </a>
   
@@ -8119,9 +8119,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#deps-tool" class="md-nav__link">
+  <a href="#deps-alias" class="md-nav__link">
     <span class="md-ellipsis">
-      :deps tool
+      :deps alias
     </span>
   </a>
   
@@ -8235,7 +8235,7 @@ <h1 id="clojure-cli-built-in-commands">Clojure CLI Built-in commands<a class="he
 <p><code>clj</code> is a wrapper script for the <code>clojure</code> command (<code>rlwrap</code> required) to add command history to the basic REPL prompt.</p>
 <p><code>clojure -T:deps</code> to run one of several built-in commands to help work with Clojure CLI projects and libraries.</p>
 <p><code>clojure --help</code> list the available commands.</p>
-<h2 id="deps-tool">:deps tool<a class="headerlink" href="#deps-tool" title="Permanent link">λ︎</a></h2>
+<h2 id="deps-alias">:deps alias<a class="headerlink" href="#deps-alias" title="Permanent link">λ︎</a></h2>
 <p>The <code>:deps</code> aliases provides tools for managing library dependencies.  </p>
 <p>The Clojure CLI <code>-X</code> flag is used to call these tools via <code>clojure.exec</code> and take key value pairs as arguments</p>
 <table>
diff --git a/search/search_index.json b/search/search_index.json
index a2ae7211b..2171fb14e 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Practicalli Clojure","text":"<p>Practicalli Clojure is a hands-on guide to using Clojure throughout all the software development stages.  Live coding videos demonstrate the Clojure REPL workflow in action, showing how to get the most out of the unique approach the language provides.</p> <p>Discover how to make the most of Clojure CLI and community tools, drawing from commercial experiences and community discussions.</p> <p>Practical code examples are supported by discussions of the concepts behind Clojure, including functional programming, \"pure\" functions and a stateless approach with persistent data structures, changing state safely, Java interoperability and tooling around Clojure.</p> <p>John Stevenson, Practical.li</p> <p>Clojure - an elegant language for a more civilised development experience</p>"},{"location":"#clojure-repl-driven-development","title":"Clojure REPL Driven Development","text":"<p>The Clojure REPL is interactive environment used to run Clojure code in both development and production. The REPL workflow provides an instant feedback loop so individual pieces of code (expressions) can be evaluatived, quickly growing confidence with Clojure and rapidly evolving effective designs.</p>"},{"location":"#clojure-language","title":"Clojure Language","text":"<p>Clojure programming language has a strong dynamic type system and a simple syntax that is a joy to work with.  Immutable values and a pragmatic approach to pure functional programming makes it easier to create simple and highly maintainable systems. A specification library ensures values are of the correct shape, especially valuable when receiving data from outside of Clojure.</p> <p>Clojure has an open source license and a large number of open source libraries and tools.  Simple host interoperability allows a even more libraries to be leveraged.</p> <p>Adrian Cockcroft - formally Cloud Architect, Netflix</p> <p>The most productive programmers I know are writing everything in Clojure ... producing ridiculously sophisticated things in a very short time. And that programmer productivity matters.</p> <p>Clojure REPL Workflow overview Clojure REPL</p>"},{"location":"#navigate-the-book","title":"Navigate the book","text":"<p>Use the mouse or built-in key bindings to navigate the pages of the book</p> <ul> <li>P , , : go to previous page</li> <li>N , . : go to next page</li> </ul> <p>Use the search box to quickly find a specific topic</p> <ul> <li>F , S , / : open search dialog</li> <li>Down , Up : select next / previous result</li> <li>Esc , Tab : close search dialog</li> <li>Enter : follow selected result</li> </ul>"},{"location":"#resources","title":"Resources","text":"<p> Practicalli Clojure CLI Config - additional tools via aliases Clojure Aware Editors Practicalli YouTube channel</p>"},{"location":"#sponsor-practicalli","title":"Sponsor Practicalli","text":"<p>All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.</p> <p>Thanks to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support</p>"},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images &amp; stylesheets)."},{"location":"core-async/","title":"Core.async","text":""},{"location":"core-async/#discussion-from-the-clojurians-clojure-uk-slack-channel","title":"Discussion from the clojurians clojure-uk slack channel","text":"<p>recommendation / intro tutorial</p> <p>https://github.com/clojure/core.async/blob/master/examples/walk-through.clj</p> <p>EuroClojure talk about clojure otp library that built on top of core.async because they felt it was too low level</p> <p>At the REPL</p> <ul> <li>if you don\u2019t create channels with non-zero sized buffers, or don\u2019t perform operations in separate threads or go-blocks, then you can end up blocked quite easily</li> </ul> <p>In production be sure to catch exceptions, or at least be logging them. It can be too easy to loose errors (and the processes that threw them)</p> <p>if you make a note of the nrepl port when you start a repl, you can always connect a second repl to the same process to recover from accidental blocking</p>"},{"location":"core-async/#coreasync-and-transducers","title":"core.async and transducers","text":"<p>core.async + transducers</p>"},{"location":"core-async/#manifold-alternative-to-coreasync","title":"Manifold - alternative to core.async","text":"<p>another approach is to use <code>manifold</code></p> <p>it\u2019s use of deferred values makes it harder to block the REPL - but obviously the buffering still has to happen somewhere!</p> <p><code>manifold</code> for general async stuff more than <code>core.async</code></p> <p>use core.async as a way of chaining together bits of data processing. manifold would be good for that too</p> <p>put multiple calls to an external API on a channel and have them \u201cdo their thing\u201d in their own time in the background.  This seems to be a good use for core.async\u2026  Is Manifold is as good / better?</p> <p>If processing streams of data then <code>core.async</code> is fine (as are manifold <code>Stream</code>s) If calls are better suited to promises then consider manifold <code>Deferred</code> If you are wanting streams of promises then manifold is a more complete solution (because the manifold <code>stream</code> and <code>deferred</code> work easily together</p> <p>API calls are generally more promise-like than stream-like (unless your result is an SSE stream or websocket etc)</p> <p>there are <code>promise-chan</code>s in core.async too though</p> <p>Manifold could be used to collect a number of remote resources together in a <code>let</code> which isn't very stream like</p> <p>manifold has two distinct core abstractions - the <code>deferred</code>, which is a promise with callbacks and additional machinery, and the <code>stream</code> which is a umm stream of values, and supports buffering, backpressure etc</p> <p>First call to the API I will get a total back as part of the result and as there is no paging functionality \u201cbuilt in\u201d on the API in question I will need to take the total and figure out how many more calls I need to make to get the \u201crest\u201d of the data.  I was going to do this by throwing the calls onto a channel using core.async\u2026 I am sensing that their promise-y nature would, you feel, be better suited to Manifold Deferred..? a stream or a channel works quite well for that sort of query in my data access lib we actually use a promise of a stream for that sort of access which is an improvement over just a plain stream because it allows easy mixing with other calls which return promises of a value</p> <p>I was intending to stack up API operations in a channel as a queue so that a) I don\u2019t block execution and b) so that I don\u2019t have to use an actual queue (SQS / rabbitMQ etc) I am starting to think I may not have understood the implications of what I want to do\u2026 </p> <p>i'm not sure - are you just trying to get a stream of records from a paginated api ?</p> <p>what are you trying to not block the execution of?</p> <p>The API is not paginated, I need to figure out how many pages there are and stack up the calls.</p> <p>can you pass an offset or something ?</p> <p>What I am looking for is a way to stack work up asynchronously in the background so that my call(s) to the external API don\u2019t lock up the whole app / program for minutes at a time.</p> <p>yes, but there is no \u201cnext\u201d call - the offset and page-size are arbitrary params every call, there is no way to ask for \u201cpage 2 of my last query to the API\u201d</p> <p>a channel of results in core.async is perfectly reasonable, as is a manifold stream of deferred responses</p> <p>so:</p> <ol> <li>Make call for first page</li> <li>Process first page (hopefully async)</li> <li>Use total to work out how many more ops I need to make</li> <li>Fill up channel with calls</li> <li>Consume channel \u201celsewhere\u201d.</li> </ol> <p>is my thesis - does that make sense..?</p> <p>what is the main thread in this context? the app that \u201cruns\u201d which in turn is a hybrid API / webapp</p> <p>core.async itself uses a threadpool, so you might not need to funnel them all down one channel unless you wanted to limit the number of concurrent api calls I would like to do as much concurrently as possible, but it\u2019s not a deal-breaker, serial is fine as long as the work can be \u201ckicked off\u201d and left going. order of results being processed is not important, so concurrency (particularly if it makes the whole thing faster) would be great.</p> <p>I need to make one call to find out how many results match the request, the vendor / curator of the AI in question is not prepared to produce a simplified response to figure out the size of results sets, so I am stuck with that.</p> <p>I am assuming that I need to \u201cdef\u201d the channel(s) and then have a form that is in an evaluated namespace that is \u201cwaiting\u201d for the channel(s) to have something on them..?</p> <p>a common idiom is to return channels/streams/promises as the result of a query fn</p> <p>OK, but how would I consume them without tying up the main thread?</p> <p>many options</p> <ul> <li>put the consuming code inside a core.async <code>go</code> block</li> <li>create a new channel with a transducer and pipe your first channel to that</li> <li>have your api fn take the channel you want responses put on and pass in a channel with a transducer</li> </ul> <p>similarly in manifold,</p> <ul> <li>chain a step onto a deferred https://github.com/ztellman/manifold/blob/master/docs/deferred.md#composing-with-deferreds</li> <li>map a fn over a stream https://github.com/ztellman/manifold/blob/master/docs/stream.md#stream-operators</li> </ul> <p>need some code in an evaluated namespace that was effectively \u201clistening\u201d for there to be \u201cthings\u201d on the channel, just a form at the end of my namespace containing a go block that was consuming a named channel onto which my API function would place \u201cthings\u201d</p> <p>most web or UI frameworks will already have an event loop to do that i\u2019d have expected?</p> <p>order of ops:</p> <ol> <li>Make first query to API</li> <li>Process result, including calculation of how many more ops required</li> <li>Load up a channel with the other calls</li> </ol> <p>It\u2019s an app that will periodically (every hour / day not sure yet) make calls to an API, stash the returned data in a database and an ElasticSearch cluster, and then do it all again the next time.</p> <p>might want to add [4] concatenate results from each of the page queries into a single record stream</p> <p>but what will consume the eventual record stream ?</p> <p>This makes the API into a smaller, custom dataset that can be interrogated via Kibana</p> <p>I am not saying I don\u2019t want to add \u201c[4] concatenate results from each of the page queries into a single record stream\u201d, but I can\u2019t think of why I would do that, and that is probably me being ignorant of the benefits etc.  Please could you explain to me why I would add this step - I really am asking, not being a prick, I promise </p> <p>do you want to expose your downstream consumers to an additional level of structure (pages) which is an implementation feature of the upstream API  ?</p> <p>No</p> <p>I want to take each of the 100 / 1000 / 10000 results and store them as individual documents in ES and as JSONB fields in Postgres</p> <p>The API I am \u201charvesting\u201d has a 90 day sliding window, so over time the queries I make will have different results.  I don\u2019t want to keep track of the last article I harvested, nor do I want to have to \u201cfind\u201d it in the results to then get all the newer ones.  It\u2019s easier to just \u201ceat\u201d the whole response every time and reply on ES refusing to re-import a document with an existing id (into the same index) and on postgres\u2019s ability to enforce a \u201cunique\u201d index on the id field.</p> <p>but I can\u2019t \u201cget\u201d all of the results in one query, the API limits \u201cpages\u201d to 1000 results, so I need to be able to stack up calls and execute them in an async, non-blocking manner.</p> <p>yep, so you can concatenate the pages into a single record-stream, and process each of the records individually</p> <p>OK, I like the sound of this in principle, and I think I am sort of doing that already with the synchronous, manual approach, as I get 100 articles back and then I do a doseq over the vector of maps to do INSERT queries into postgres and PUT calls to ES</p> <p>What do you mean by a \u201crecord-stream\u201d?</p> <p>by \"record stream\" i mean a conceptual sequence of individual records... could be on a core.async <code>chan</code> or a manifold <code>stream</code></p> <p>the benefit is just simplicity - a sequence of individual records is a simpler thing than a sequence of pages of individual records... but there are tradeoffs - sometimes you want to deal with pages of records</p> <p>Oh I see!  Right, yeah, I was just going to consume the channel of returned promises with the doseq I already have, so concatenating them together into one HUGE vector first seemed like a redundant step. i.e. one of the queries I am going to do returns (currently) a little over 13,000 records - I was expecting to grab the results of 14 promises off the channel and \u201cdoseq\u201d each one until the channel was empty</p> <p>I suppose I could consume them off the channel into one big vector, or indeed another channel and then have another consumer running what currently runs inside the doseq on each map / JSON blob that comes out of the channel\u2026  Is that what you mean?</p> <p>so:</p> <p>channel of promises consumer turns vector of maps into another channel of individual maps consumer2 puts maps into DB and ES off second channel</p> <p>i meant another channel, yes</p> <p>possibly even:</p> <p>consumer2 puts maps into DB and onto another channel consumer3 puts maps on third channel into ES</p> <p>(as an aside @maleghast , doing any long-running or blocking processing in a vanilla core.async <code>go</code> block isn't a good idea - there is a fixed-size core.async threadpool which you can exhaust, causing blocking - so you can use https://clojure.github.io/core.async/index.html#clojure.core.async/thread )</p> <p>So if I use thread inside a go block, or instead of a go block..?</p> <p>here is an example</p> <p><code>(async/go   (let [v (async/&lt;! (async/thread (do-blocking-stuff)))]     (do-non-blocking-stuff v))</code></p> <p>something like that</p>"},{"location":"core-async/#long-running-processes","title":"Long running processes","text":"<p>also, beware long-running processes in core.async that expand items with eg. <code>mapcat</code> operations. You can break back pressure that way. (ie. pages on a channel being expanded into multiple events)</p> <p>ooo i haven't come across that problem  what happens ?</p> <p>requires a very specific use case to be a problem, but it\u2019s caught a few people out: https://stackoverflow.com/questions/37953401/where-is-the-memory-leak-when-mapcat-breaks-backpressure-in-core-async</p> <p>Where is the memory leak when mapcat breaks backpressure in core.async? I wrote some core.async code in Clojure and when I ran it it consumed all available memory and failed with an error. It appears that using mapcat in a core.async pipeline breaks back pressure. (Whi...</p> <p>you\u2019re not likely to hit it unless you are using a lot of transforms on your channels, and then its easily worked around, but it can work fine in test, and then blow up in prod with more data/longer running processing</p>"},{"location":"explaining-macros/","title":"Explaining Macros","text":"<p>The macro system allows you to extend the design of the Clojure language, without waiting for the language designers.</p> <p>Expose as much of your API as possible as functions so that they can be stored in hash-maps, mapped over sequences of widgets, negated with complement, juxtaposed with juxt, and so on.</p> <p>Only define your own macros when functions are insufficient or there is a very common abstraction that creates a simpler system.</p>"},{"location":"explaining-macros/#hintclojure-macros-are-quite-unique","title":"Hint::Clojure macros are quite unique","text":"<p>Many languages have macros, although most are more akin to a template systems.</p> <p>Clojure macros are a language within the Clojure language that generate Clojure code when the Clojure Reader parses a macro.  In fact the Clojure Reader will pass the macro to the macro reader which does the expansion.</p>"},{"location":"explaining-macros/#hintevery-macro-adds-maintenance-cost","title":"Hint::Every Macro adds maintenance cost","text":"<p>Adding custom macros adds a higher maintenance cost to a codebase and increased the amount of on-boarding of developers onto a project.</p> <p>Custom macros are additional abstractions to learn when working with a project that are not common across projects in the same way as clojure.core or common libraries.</p>"},{"location":"explaining-macros/#functional-composition-and-macros","title":"Functional composition and Macros","text":"<p>Macros do not compose functionally</p> <p>Macros in Clojure aren't values. They can't be passed as arguments to other functions or macros, can't be returned as the result of computations, and can't be stored in data structures.</p> <p>If macros were values and used as arguments to functions then the compile cycle of Clojure would need to change, otherwise the results of macro expansion wouldn't be known until runtime and could even vary between function calls.</p>"},{"location":"explaining-macros/#wrapping-macros-in-functions-for-composition","title":"Wrapping Macros in functions for composition","text":"<p>It is possible to wrap a macro in a function and then that macro can be used as part of a functionally composed expression.</p> <pre><code>(reduce and [true true false true])\n;;=&gt; RuntimeException\n\n(reduce #(and %1 %2) [true true false true])\n;;=&gt; false\n</code></pre> <p>If you are doing this, then its more probably that a simple function would be a better approach.</p>"},{"location":"io/","title":"IO in Clojure","text":"<p>From http://blog.isaachodes.io/p/clojure-io-p1/</p> <p>The Ins and Outs of Clojure: Part I November 13, 2010</p> <p>(Written about Clojure 1.2.)</p> <p>It is a truth universally acknowledged, that a programmer using Clojure will want to perform IO. Let me help you out (put).</p> <p>I\u2019ll go over some of the basics of IO, focusing on what you can use Clojure to do directly. I\u2019ll move on after the basic introduction, to some of the more interesting and generally useful classes that Java offers, giving a little context for each. In</p> <p>Reading files in is generally one of the first things I want to do when playing with a new language, so I\u2019ll start there. Before I get started though, I should mentioned that in Clojure, strings are always encoded using UTF-16. Generally this saves time and worry, but it\u2019s something to keep in mind should you run into problems on the encoding front. slurp</p> <p>Clojure comes with a handy little function called slurp that takes in a string representing a filename (or, really, pretty much anything; a File, a stream, a byte array, URL, etc) and returns a string containing the contents of your file. It\u2019s pretty handy if you just need to get some information from a file that\u2019s relatively small, and you\u2019ll be parsing it yourself.</p> <p>(slurp \"/home/user/file.txt\") =&gt; \"A little bit\\nof information here.\"</p> <p>A nice thing about slurp is that you can easily build up file paths with str. For example, say you want to output to a file based on information you find at runtime:</p> <p>(slurp (str \"/home/\" username \"/projects/\" filename))</p> <p>But slurp is pretty basic, and once your files get large enough, totally impractical. Nonetheless, it\u2019s a handy function to know about.</p> <p>As a useful and comical aside, the function spit is the counterpart to slurp, except that instead of reading input, spit does output. More on this in a future article, though. line-seq</p> <p>One of my favorite IO functions has got to be line-seq; line-seq takes a reader object (which must implement BufferedReader) and returns a lazy sequence of the lines of the text the reader supplies. This is handy when you\u2019re dealing with files (if this offends you, taking a Unix approach here for now and say that everything is a file) that are too big to merely slurp, but that are \\newline delimited (or CR/LF delimited, if you\u2019re of the Windows persuasion).</p> <p>(use '[clojure.java.io '(reader)]) (take 2   (line-seq (reader \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>Notice how we take 2 from the sequence we get from using line-seq. We can take as much or as little as we need; we won\u2019t be reading much (Clojure will read a bit more than you tell it to in order to get more IO performance, but let\u2019s not worry about that) more than we specify. We can do anything we want with the resulting seq; that\u2019s the beauty of line-seq and the ubiquitous sequence abstraction.</p> <p>Back in the day, Clojurists had to sink a little lower than the clojure.java.io namespace to use line-seq; two Java classes were needed. One of these Java classes is the most wondrous and amazing thing just below the surface of the more elegant and beautiful Clojure code; BufferedReader. Here\u2019s how we used to do it;</p> <p>(import '(java.io FileReader BufferedReader)) (take 2   (line-seq (BufferedReader.               (FileReader. \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>This might give you a better sense of what\u2019s going on when you use reader, though in reality reader is far more complicated than just that: you can trust it to handle a variety of \u201creadable things\u201d and return to you a BufferedReader if possible.</p> <p>FileReader will return a Reader on a file, and BufferedReader takes and buffers a Reader, as you might have extrapolated from the name. Readers are basically just objects upon which a few methods (like read, skip and close) may be enacted and expected to return reasonable results. line-seq essentially reads up until a line-delimiter and returns the read chunk as an element in the sequence it is generating.</p> <p>While on the subject of files, I should probably mentioned the file function, from clojure.java.io. file takes in an arbitrary number of string arguments, and pieces them together into a file hierarchy, returning a File instance. This can come in handy. Rivers? inputStreams? Brooks?</p> <p>Streams are an especially useful class of readers. Oftentimes you\u2019re reading in text; that\u2019s what Readers do. But often you need to read in a stream of bytes; that\u2019s where you need to use clojure.java.io\u2019s input-stream.</p> <p>(use '[clojure.java.io '(reader)]) (def g (input-stream \"t.txt\")) (.read g) =&gt; 105 (.read g) =&gt; 115 (char (.read g)) =&gt; \\space</p> <p>As you can see, instead of getting characters from this file (like we get when we use a reader), we\u2019re getting integer byte values. This can be useful when reading, for example, a media file.</p> <p>In general, strings are always UTF-16, which are 16-bit pieces of data, whereas byte-streams are 8-bit pieces of data. It bears repeating that the stream operators should be used when you\u2019re not dealing with strings: they are not trivially interchangeable, as they might be in other languages where strings are syntactic sugar for byte arrays. RandomAccessFile</p> <p>Finally, let me introduce to you a spectacularly useful Java class. RandomAccessFile is a class which allows you to quickly jump around in a large file, and read bytes from it.</p> <p>(import '(java.io RandomAccessFile)) (def f (RandomAccessFile. \"stuff.txt\" \"r\"))</p> <p>Note the second argument of the constructor, \u201cr\u201d; this indicates that we\u2019re opening the file just for reading. Now that we have f, we can use it to navigate and read the file:</p> <p>(.read f) =&gt; 105 (.length f) =&gt; 2015 ;; this is the number of bytes this file is in length (.skipBytes f 20) (.getFilePointer h) =&gt; 21 ;; the position we're at in the file (.read f) =&gt; 89</p> <p>As you can see, you can jump around (quickly!) through a file, and read from the parts you want, and skip the parts you do not want. The key methods/functions here (among many others that can also be useful; be sure to check the documentation) are read, length, skipBytes, seek and getFilePointer. Closing</p> <p>Every file that is opened should be closed, and what we\u2019ve been doing is a little unsafe. In order to close an open reader/file, we should use the close method on it; in the above example, when you\u2019re done with f, simply execute (.close f) to tell the file system that you\u2019re done with the file. Alternatively, and more idiomatically, you can open your files with the handy with-open binder:</p> <p>(with-open [f (RandomAccessFile. \"stuff.txt\" \"r\")]   (.read f))</p> <p>When you\u2019re done with f, Clojure will close it, and you won\u2019t have to worry one iota about it. Digging Deeper</p> <p>Should slurp and line-seq not be enough for your reading needs (and chances are that, should you code enough in Clojure, they won\u2019t always been), you might want to explore clojure.java.io some more, as well as some of the Java classes (namely, those stemming from Reader and BufferedReader, as well as InputStream and BufferedInputStream) mentioned above. See my previous article on using Java if you\u2019re unfamiliar with using Java.</p> <p>Next up is an introduction to the \u201couts\u201d of Clojure and Java. Stay tuned!</p> <p>I owe a big thank you to Phil Hagelberg for reading over this essay and offering advice. If you don\u2019t already, you should be using his Leiningen for both dependency management and a stress-free development environment.</p> <p>The Ins and Outs of Clojure: Part I November 13, 2010</p> <p>(Written about Clojure 1.2.)</p> <p>It is a truth universally acknowledged, that a programmer using Clojure will want to perform IO. Let me help you out (put).</p> <p>I\u2019ll go over some of the basics of IO, focusing on what you can use Clojure to do directly. I\u2019ll move on after the basic introduction, to some of the more interesting and generally useful classes that Java offers, giving a little context for each. In</p> <p>Reading files in is generally one of the first things I want to do when playing with a new language, so I\u2019ll start there. Before I get started though, I should mentioned that in Clojure, strings are always encoded using UTF-16. Generally this saves time and worry, but it\u2019s something to keep in mind should you run into problems on the encoding front. slurp</p> <p>Clojure comes with a handy little function called slurp that takes in a string representing a filename (or, really, pretty much anything; a File, a stream, a byte array, URL, etc) and returns a string containing the contents of your file. It\u2019s pretty handy if you just need to get some information from a file that\u2019s relatively small, and you\u2019ll be parsing it yourself.</p> <p>(slurp \"/home/account/projects/config.txt\") =&gt; \"A little bit\\nof information here.\"</p> <p>A nice thing about slurp is that you can easily build up file paths with str. For example, say you want to output to a file based on information you find at runtime:</p> <p>(slurp (str \"/home/\" username \"/projects/\" filename))</p> <p>But slurp is pretty basic, and once your files get large enough, totally impractical. Nonetheless, it\u2019s a handy function to know about.</p> <p>As a useful and comical aside, the function spit is the counterpart to slurp, except that instead of reading input, spit does output. More on this in a future article, though. line-seq</p> <p>One of my favorite IO functions has got to be line-seq; line-seq takes a reader object (which must implement BufferedReader) and returns a lazy sequence of the lines of the text the reader supplies. This is handy when you\u2019re dealing with files (if this offends you, taking a Unix approach here for now and say that everything is a file) that are too big to merely slurp, but that are \\newline delimited (or CR/LF delimited, if you\u2019re of the Windows persuasion).</p> <p>(use '[clojure.java.io '(reader)]) (take 2   (line-seq (reader \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>Notice how we take 2 from the sequence we get from using line-seq. We can take as much or as little as we need; we won\u2019t be reading much (Clojure will read a bit more than you tell it to in order to get more IO performance, but let\u2019s not worry about that) more than we specify. We can do anything we want with the resulting seq; that\u2019s the beauty of line-seq and the ubiquitous sequence abstraction.</p> <p>Back in the day, Clojurists had to sink a little lower than the clojure.java.io namespace to use line-seq; two Java classes were needed. One of these Java classes is the most wondrous and amazing thing just below the surface of the more elegant and beautiful Clojure code; BufferedReader. Here\u2019s how we used to do it;</p> <p>(import '(java.io FileReader BufferedReader)) (take 2   (line-seq (BufferedReader.               (FileReader. \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>This might give you a better sense of what\u2019s going on when you use reader, though in reality reader is far more complicated than just that: you can trust it to handle a variety of \u201creadable things\u201d and return to you a BufferedReader if possible.</p> <p>FileReader will return a Reader on a file, and BufferedReader takes and buffers a Reader, as you might have extrapolated from the name. Readers are basically just objects upon which a few methods (like read, skip and close) may be enacted and expected to return reasonable results. line-seq essentially reads up until a line-delimiter and returns the read chunk as an element in the sequence it is generating.</p> <p>While on the subject of files, I should probably mentioned the file function, from clojure.java.io. file takes in an arbitrary number of string arguments, and pieces them together into a file hierarchy, returning a File instance. This can come in handy. Rivers? inputStreams? Brooks?</p> <p>Streams are an especially useful class of readers. Oftentimes you\u2019re reading in text; that\u2019s what Readers do. But often you need to read in a stream of bytes; that\u2019s where you need to use clojure.java.io\u2019s input-stream.</p> <p>(use '[clojure.java.io '(reader)]) (def g (input-stream \"t.txt\")) (.read g) =&gt; 105 (.read g) =&gt; 115 (char (.read g)) =&gt; \\space</p> <p>As you can see, instead of getting characters from this file (like we get when we use a reader), we\u2019re getting integer byte values. This can be useful when reading, for example, a media file.</p> <p>In general, strings are always UTF-16, which are 16-bit pieces of data, whereas byte-streams are 8-bit pieces of data. It bears repeating that the stream operators should be used when you\u2019re not dealing with strings: they are not trivially interchangeable, as they might be in other languages where strings are syntactic sugar for byte arrays. RandomAccessFile</p> <p>Finally, let me introduce to you a spectacularly useful Java class. RandomAccessFile is a class which allows you to quickly jump around in a large file, and read bytes from it.</p> <p>(import '(java.io RandomAccessFile)) (def f (RandomAccessFile. \"stuff.txt\" \"r\"))</p> <p>Note the second argument of the constructor, \u201cr\u201d; this indicates that we\u2019re opening the file just for reading. Now that we have f, we can use it to navigate and read the file:</p> <p>(.read f) =&gt; 105 (.length f) =&gt; 2015 ;; this is the number of bytes this file is in length (.skipBytes f 20) (.getFilePointer h) =&gt; 21 ;; the position we're at in the file (.read f) =&gt; 89</p> <p>As you can see, you can jump around (quickly!) through a file, and read from the parts you want, and skip the parts you do not want. The key methods/functions here (among many others that can also be useful; be sure to check the documentation) are read, length, skipBytes, seek and getFilePointer. Closing</p> <p>Every file that is opened should be closed, and what we\u2019ve been doing is a little unsafe. In order to close an open reader/file, we should use the close method on it; in the above example, when you\u2019re done with f, simply execute (.close f) to tell the file system that you\u2019re done with the file. Alternatively, and more idiomatically, you can open your files with the handy with-open binder:</p> <p>(with-open [f (RandomAccessFile. \"stuff.txt\" \"r\")]   (.read f))</p> <p>When you\u2019re done with f, Clojure will close it, and you won\u2019t have to worry one iota about it. Digging Deeper</p> <p>Should slurp and line-seq not be enough for your reading needs (and chances are that, should you code enough in Clojure, they won\u2019t always been), you might want to explore clojure.java.io some more, as well as some of the Java classes (namely, those stemming from Reader and BufferedReader, as well as InputStream and BufferedInputStream) mentioned above. See my previous article on using Java if you\u2019re unfamiliar with using Java.</p> <p>Next up is an introduction to the \u201couts\u201d of Clojure and Java. Stay tuned!</p> <p>I owe a big thank you to Phil Hagelberg for reading over this essay and offering advice. If you don\u2019t already, you should be using his Leiningen for both dependency management and a stress-free development environment.</p>"},{"location":"lazy-evaluation/","title":"Lazy evaluation","text":"<p><code>repeat</code></p>"},{"location":"testing-in-clojure/","title":"Testing in clojure","text":"<p>My recommended Clojure testing setup</p> <p>kaocha test runner in watch mode</p> <p>Occasionally, either on Stack Overflow or in the Clojurians Slack group, someone will ask what tools they should use to test Clojure code. Below is what I would currently recommend. I\u2019ve come to this recommendation through observing teams using a variety of testing tools and through my own use them.</p> <p>Use clojure.test with humane-test-output and lein-test-refresh.</p> <p>Use clojure.test</p> <p>clojure.test is ubiquitous and not a big departure from other languages' testing libraries. It has its warts but your team will be able to understand it quickly and will be able to write maintainable tests.</p> <p>Use humane-test-output</p> <p>You should use clojure.test with humane-test-output. Together they provide a testing library that has minimal additional syntax and good test failure reporting.</p> <p>Use lein-test-refresh</p> <p>If you\u2019re not using a tool that reloads and reruns your tests on file changes then you are wasting your time. The delay between changing code and seeing test results is drastically reduced by using a tool like lein-test-refresh. Nearly everyone I know who tries adding lein-test-refresh to their testing toolbox continues to use it. Many of these converts were not newcomers to Clojure either, they had years of experience and had already developed workflows that worked for them.</p> <p>Use lein-test-refresh\u2019s advanced features</p> <p>lein-test-refresh makes development better even if you don\u2019t change any of its settings. It gets even better if you use some of its advanced features.</p> <p>Below is a stripped down version of my ~/.lein/profiles.clj. The :test-refresh key points towards my recommended lein-test-refresh settings.</p> <p>{:user {:dependencies [[pjstadig/humane-test-output \"0.8.0\"]]         :injections [(require 'pjstadig.humane-test-output)                      (pjstadig.humane-test-output/activate!)]         :plugins [[[com.jakemccrary/lein-test-refresh \"0.16.0\"]]]         :test-refresh {:notify-command [\"terminal-notifier\" \"-title\" \"Tests\" \"-message\"]                        :quiet true                        :changes-only true}}}</p> <p>These settings turn on notifications when my tests finish running (:notify-command setting), make clojure.test\u2019s output less verbose (:quiet true), and only run tests in namespaces affected by the previous code change (:changes-only true). These three settings give me the quickest feedback possible and free me from having the terminal running lein test-refresh visible.</p> <p>Quick feedback lets you make changes faster. If you\u2019re going to write tests, and you should write tests, having them run quickly is powerful. After years of writing Clojure, this is my current go-to for testing Clojure code and getting extremely fast feedback.</p> <p>I use test-refresh every day. Frankly I'm not sure how one can program effectively without it. I especially like being able to control the notifications</p>"},{"location":"alternative-tools/","title":"Alternative Tools","text":""},{"location":"alternative-tools/clojure-cli/basic-repl/","title":"Basic Terminal REPL UI","text":"<p>The <code>clojure</code> command will start a REPL by default or if given the <code>--repl</code> or <code>-r</code> argument.  The basic repl does not provide history of commands.</p> <p><code>clj</code> is a script that wraps the <code>clojure</code> command and requires <code>rlwrap</code>, an external readline command, to navigate REPL history via the Up and Down keys.</p> <p>Use <code>clj</code> when you want to run a repl (or preferably use rebel readline instead) and <code>clojure</code> for everything else.</p> <p>Rebel Rich Terminal UI</p> <p>rebel readline is a terminal REPL UI that provides interactive help, function autocomplete, signature prompts and many other features to provide a very rich REPL experience.</p> <p> Practicalli Clojure CLI Config includes the <code>-M:repl/rebel</code> alias to run rebel readline REPL.</p> <p><code>clj</code> command in a terminal window starts a Clojure REPL and shows the version of Clojure used.  The command does not need to be in a directory containing a Clojure project.</p> <pre><code>clj\n</code></pre> <p>Type in a Clojure expression at the <code>=&gt; user</code> REPL prompt and press Enter to see the result</p> <p>Ctrl+d to exit the REPL</p> <p></p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/","title":"Clojure Automation Aproaches","text":"<p>Leiningen, Clojure CLI tools and Boot are different approaches to Clojure project configuration.  Regardless of the tool used, the Clojure code in the project remains the same.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#clojure-cli-tools-overview","title":"Clojure CLI tools overview","text":"<p>Clojure CLI tools takes a very simple approach, focusing on running a REPL process, Clojure programs via clojure main and specific functions via clojure exec.  With the Clojure exec approach any function can be called as the entry point to running an application or tool written in Clojure.</p> <p>CLI tools can use both Maven and Git repositories for dependency management.  Code from a Git repository dependency can be used without packaging it into a library (Java jar file), simplifying the use of libraries under active development.</p> <p>Clojure CLI tools provides a comprehensive set of features via community tools.  These community tools are provided via aliases in the user level configuration for all projects (e.g. practicalli/clojure-deps-edn) or an alias for a specific project <code>deps.edn</code> configuration.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#leiningen-overview","title":"Leiningen overview","text":"<p>Leiningen is a feature rich tool which is simple to get started with a plugin extension to add more functionality.  Leiningen does use more resources as it starts a Java Virtual machine to run itself and another to run the application.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#boot-overview","title":"Boot overview","text":"<p>Boot runs tasks written in Clojure on the command line, providing a flexible way to work with projects.  However, this approach does require expertise with Clojure and  Clojure scripts to work with projects.</p> <p>Clojure code is the same which ever approach used</p> <p>The Clojure code for the project will be the same regardless of which tool is used to configure and manage the Clojure project.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#configuration","title":"Configuration","text":"Tool Project Config User Config Extension Clojure CLI tools deps.edn hash-map merged with user config <code>$XDG_HOME_CONFIG/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code> aliases in project and user deps.edn Leiningen project.clj and <code>defproject</code> macro ~/.lein/profiles.clj Leiningen specific plugin Boot build.boot with <code>deftask</code>, <code>task-options!</code>, <code>set-env!</code> Write the tasks required in Clojure Clojure CLILeiningenBoot <p>Clojure CLI tools are configured with an EDN data structure, i.e. a hash-map of key-value pairs.  As this is a Clojure data structure its much easier to parse and should be very familiar to Clojure developers.</p> <p>Leiningen projects are configured with a <code>project.clj</code> file which contains a <code>defproject</code> macro with a great many options.  The Leiningen tutorial explains the options in detail.  A sample project.clj contains examples of using each of this options.</p> <p>For most projects all the configuration resides in the project.clj file.  Exceptions to this include figwheel-main, which also adds it own EDN configuration and EDN build configuration files.</p> <p>Leiningen also has a user level configuration</p> <p><code>build.boot</code> is a file containing Clojure code that defines the tasks for using your project.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#extending-the-tools","title":"Extending the tools","text":"Clojure CLILeiningenBoot <p>Clojure CLI tools has been designed for a very specific role, to provide a lightweight wrapper over running Clojure programs and via tools.deps managing dependencies from Maven and Git repositories.</p> <p>The projects that extend Clojure CLI tools are self-contained libraries and tools, so are not tied to any one particular tool.  Any general tools written for Clojure should work with Clojure CLI tools by calling their main function (clojure main) or a specifically named function (clojure exec)</p> <p>Leiningen plugin extension was the main way to extend the functionality of Leiningen (or getting pull requests accepted to the Leiningen projects).</p> <p>Although there are several plugins that were widely adopted, some plugins eventually caused more confusion than benefit or were simply trivial and in the main plugins seem to have become less important to the Clojure community.</p> <p>One of the limitations of Leiningnen plugin mechanism was not being able to exclude any configuration in a users <code>.lein/profiles.clj</code> file, so there was greater potential for conflict.</p> <p>The recommended way to extend Leiningen is to not write plugins, but to include aliases that define a qualified function to run when that alias is used with the Leiningen command.</p> <p>Write clojure to define scripts to run with boot projects.</p> <p>Babashka for Clojure scripting</p> <p>Babashka is an approach to writing bash-style scripts using the Clojure language.  Babashka bundles additional libraries to support common tasks</p>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/","title":"Evaluating an expression with Clojure CLI tools","text":"<p>An expression is a piece of Clojure code that can be evaluated and return a result</p> <p>This expression calls the <code>+</code> function with the arguments <code>1 2 3 4 5</code>.  As this code works, we get a result.</p> <pre><code>(+ 1 2 3 4 5)\n</code></pre> <p>Using the <code>-e</code> option an expression can be passed to the Clojure CLI tools and a value returned</p> <pre><code>clojure -e (+ 1 2 3 4 5)\n</code></pre>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/#expressions-returning-nil","title":"Expressions returning <code>nil</code>","text":"<p>If the expressing used returns a value of <code>nil</code>, a legal value in Clojure, then no result is printed out.</p>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/#when-to-use-this","title":"When to use this?","text":"<p><code>clojure -e</code> is a quick way to see what an expression does without having to set anything up (although starting a REPL is very little extra effort).</p> <p>Using the <code>-e</code> option is useful for running simple scripts written in Clojure, especially on servers and remote environments.</p> <p>The lack of return value for nil is very useful when using Clojure CLI tools to evaluate Clojure code within another script.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/","title":"Set namespace on REPL startup","text":"<p>The REPL process does not evaluate project code on start-up.  If it did and that code had a error, it could prevent the REPL from starting.</p> <p>The common approach is to require the main namespace for the project, making the functions in that namespace available.  This will also make available functions from those namespaces.</p> <p>Switching to a specific namespace in the REPL allows calling functions by name, without the fully qualified name.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-via-the-command-line","title":"Set namespace via the command line","text":"<p>To require and switch to a namespace on startup, use the <code>clojure</code> or <code>clj</code> commands with the --eval option to run the specific commands.  The --repl option will ensure the repl starts.</p> <pre><code>clj --eval \"(require 'practicalli.random-clojure-core-function)\" --eval \"(in-ns 'practicalli.random-clojure-core-function)\" --repl\n</code></pre> <p><code>-r</code> or <code>(clojure.main/repl)</code> are the same as using the <code>--repl</code> option</p> <pre><code>clj -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly 'foo.bar))\" -r\nclj -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly 'foo.bar)) (clojure.main/repl)\"\n</code></pre>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-with-rebel-readline","title":"Set namespace with Rebel Readline","text":"<p>Set the namespace using Rebel Readline alias from  Practicalli Clojure CLI Config</p> <pre><code>clj -M:lib/rebel -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly (find-ns 'foo.bar)))\" -m rebel-readline.main\n\n#object[clojure.lang.Namespace 0x46cf05f7 \"foo.bar\"]\n[Rebel readline] Type :repl/help for online help info\nfoo.bar=&gt;\n</code></pre> <p>The <code>:lib/rebel</code> alias adds the rebel library as a dependency without calling clojure main on the rebel namespace.  <code>alter-var-root</code> sets the namespace. The <code>-m</code> flag defines the namespace which Clojure main will run the <code>-main</code> function from, starting the rebel UI on the command line.</p> <p>The <code>--eval</code> approach will be blocked if used with aliases that set the main namespace, such as <code>:repl/rebel</code>.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-using-an-editor","title":"Set namespace using an editor","text":"<p>It is not necessary to set the namespace when evaluating code in a Clojure aware editor.  Expressions are evaluated within the scope of the namespace in which they are defined.</p> <p>Using an editor to evaluate Clojure is much simpler and quicker than using a command line REPL, especially when working with Clojure projects with more than one namespace.</p>"},{"location":"alternative-tools/data-inspector/reveal/","title":"Reveal REPL with visual data browser","text":"<p>Reveal provides a REPL with a connected visual data explorer.  Reveal can also be used as a <code>tap&gt;</code> target, visualizing data added to a <code>tap&gt;</code> (an elegant approach compared to print statements).</p> <p>Reveal describes itself as a read evaluate visualize loop tool proving extra tools to explore data in Clojure visually.  The extensive documentation shows the many ways to use Reveal.</p> <p>Use Reveal with a terminal REPL or a Clojure editor that uses nrepl such as Emacs Cider and Spacemacs.  Reveal can be added as a tap source to any running REPL, eg. using Reveal with Rebel Readline.</p> <p> </p> REPL Terminal UInrepl Editors <p> Practicalli Clojure CLI Config contains the <code>:inspect/reveal</code> alias to run Reveal REPL in a terminal with the Reveal UI along-side.</p> <p>Open a terminal and run the command:</p> <pre><code>clojure -M:inspect/reveal\n</code></pre> <p>Use the <code>clj</code> command if the <code>rlwrap</code> binary is available</p> <p>Write Clojure code as normal in the REPL and result are also sent to the Reveal data browser window.</p> <p>The extensive documentation shows the many ways to use Reveal.</p> <p>Start reveal with an nREPL server to allow connection from a Clojure aware editor</p> Practicalli Clojure CLI ConfigAlias Definition <p><code>:inspect/reveal-nrepl</code> alias provided by  Practicalli Clojure CLI Config runs a Reveal repl with data browser and nrepl server, allowing connections from Clojure aware editors such as Emacs CIDER and VSCode Calva.</p> <p><code>:inspect/reveal-light-nrepl</code> does the same and uses a light them with Ubuntu Mono 32 point font (good for demos, HiDPI screens)</p> <p>Add the following aliases to your user level <code>~/.clojure/deps.edn</code> configuration to make reveal available to all projects.</p> <p>Plain nrepl server with Reveal.</p> <p><pre><code>  :inspect/reveal-nrepl\n  {:extra-deps {vlaaad/reveal {:mvn/version \"1.1.159\"}\n                nrepl/nrepl   {:mvn/version \"0.8.3\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[vlaaad.reveal.nrepl/middleware]\"]}\n</code></pre> CIDER specific nrepl connection with the Cider middleware</p> <pre><code>  :inspect/reveal-nrepl-cider\n  {:extra-deps {vlaaad/reveal                 {:mvn/version \"1.1.159\"}\n                nrepl/nrepl                   {:mvn/version \"0.8.3\"}\n                cider/cider-nrepl             {:mvn/version \"0.25.4\"}\n                refactor-nrepl/refactor-nrepl {:mvn/version \"2.5.0\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,refactor-nrepl.middleware/wrap-refactor,cider.nrepl/cider-middleware]\"]}\n</code></pre> <p>Start a Reveal REPL with nrepl server</p> <pre><code>clojure -M:inspect/reveal-nrepl\n</code></pre> <p>Connect to the Reveal repl from a Clojure aware editor, e.g <code>cider-connect</code></p>"},{"location":"alternative-tools/data-inspector/reveal/#using-reveal-with-cider-jack-in","title":"Using Reveal with Cider Jack-in","text":"<p><code>C-u cider-jack-in-clj</code> in CIDER to start a reveal REPL  (<code>SPC u , '</code> in Spacemacs)</p> <p>Edit the jack-in command by deleting the all the configuration after the <code>clojure</code> command and add the alias <pre><code>clojure -M:inspect/reveal-nrepl-cider\n</code></pre></p> <p><code>:inspect/reveal-nrepl-cider</code> is a light version of the above.</p>"},{"location":"alternative-tools/data-inspector/reveal/#cider-jack-in-with-reveal-using-a-dir-localsel","title":"Cider jack-in with reveal using a .dir-locals.el","text":"<p>Add a <code>.dir-locals.el</code> file to the root of the Clojure project. The <code>.dir-locals.el</code> configuration adds the <code>:inspect/reveal-nrepl-cider</code> via <code>cider-clojure-cli-aliases</code> and all other automatically injected configuration is disabled to prevent those dependencies over-riding the alias.</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":inspect/reveal-nrepl-cider\")\n                  (cider-jack-in-dependencies . nil)\n                  (cider-jack-in-nrepl-middlewares . nil)\n                  (cider-jack-in-lein-plugins . nil)\n                  (cider-clojure-cli-parameters . \"\"))))\n</code></pre> <p>Ensure the <code>.dir-locals.el</code> file is loaded by using <code>revert-buffer</code> on any open Clojure file from the project.</p> <p><code>cider-jack-in-clj</code> should now start the Reveal REPL and send evaluations from Cider to the Reveal visualization UI.</p>"},{"location":"alternative-tools/data-inspector/reveal/#reveal-with-rebel-and-tap","title":"Reveal with Rebel and <code>tap&gt;</code>","text":"<p>Reveal can be used as a <code>tap&gt;</code> target with the Rebel REPL, launching the Reveal data browser when added as a tap&gt; target.</p> <p>Start Rebel REPL with Reveal library as a dependency</p> <pre><code>clojure -M:repl-reveal:repl/rebel\n</code></pre> <p>Add reveal as a tap target that will receive all data from <code>tap&gt;</code> function calls</p> <pre><code>(add-tap ((requiring-resolve 'vlaaad.reveal/ui)))\n</code></pre> <p>A reveal window opens and receives all <code>tap&gt;</code> values while the REPL is running.</p> <pre><code>(tap&gt; [1 2 3 4 5])\n(tap&gt; {:name \"Jenny\" :skill \"Clojure\"})\n(tap&gt; (zipmap [:a :b :c] [1 2 3 4]))\n</code></pre>"},{"location":"alternative-tools/data-inspector/reveal/#atom-and-tapped-value","title":"Atom and Tapped value","text":"<p>Create an atom for debugging purposes</p> <pre><code>(def debug-state (atom nil))\n(add-tap #(reset! debug-state %))\n</code></pre> <p>Use <code>tap&gt;</code> to capture intermediate values in the middle of code that requires debugging, inspecting or watching the atom value (deref the atom and watch:latest or watch:all).  This approach complements an editor debugging process</p>"},{"location":"alternative-tools/data-inspector/reveal/#tracking-state-with-an-atom","title":"Tracking state with an atom","text":"<p>Define the state as an atom, the state being a simple value in this case</p> <pre><code>(def state (atom 24))\n</code></pre> <p>Select the reference created for the state in the Revel browser.</p> <p><code>SPACE</code> or <code>ENTER</code> to open the menu and select <code>Deref</code>.  A tab opens with the value of the atom.</p> <p><code>SPACE</code> or <code>ENTER</code> with the value selected and select <code>Watch:all</code>.</p> <p>In the REPL, update the value of the state atom.</p> <pre><code>(swap! state * 12)\n</code></pre> <p>The new value of the state atom is shown in the Reveal data browser.  Each Clojure expressions evaluated that affects the state atom will be displayed in the Reveal browser.</p>"},{"location":"alternative-tools/data-inspector/reveal/#running-different-types-of-repl","title":"Running different types of repl","text":"<p>Using Clojure exec <code>-X</code> flag, the default repl function can be over-ridden on the command line, supplying the <code>io-prepl</code> or <code>remote-prepl</code> functions.</p> <ul> <li><code>clojure -X:inspect/reveal io-prepl :title '\"I am a prepl repl\"</code></li> <li><code>clojure -X:inspect/reveal remote-prepl :title '\"I am a remote prepl repl\"'</code></li> </ul>"},{"location":"alternative-tools/data-inspector/reveal/#configure-theme-font","title":"Configure theme &amp; font","text":"<p>Add a custom theme and font via the <code>-J</code> command line option or create an alias using <code>:inspect/reveal-light</code> as an example.</p> <pre><code>clojure -M:inspect/reveal -J-Dvlaaad.reveal.prefs='{:theme :light :font-family \"Ubuntu Mono\" :font-size 32}'\n</code></pre>"},{"location":"alternative-tools/data-inspector/reveal/#rebel-readline-reveal-add-reveal-as-tap-source","title":"Rebel Readline &amp; Reveal: Add Reveal as tap&gt; source","text":"<p>Evaluate <code>(add-tap ((requiring-resolve 'vlaaad.reveal/ui)))</code> when using Rebel Readline to add Reveal as a tap source, showing <code>(tap&gt; ,,,)</code> expressions in the reveal window, eg. <code>(tap&gt; (map inc [1 2 3 4 5]))</code>.</p>"},{"location":"alternative-tools/leiningen/","title":"Leiningen build automation tool","text":"<p>Leiningen will help you create, build and deploy your Clojure projects.</p> <p>Practicalli recommends using Clojure CLI</p> <p>For new project, Clojure CLI is recommended as it requires fewer resources and enables a more customisable approach to configuring project and running tools to support Clojure development.</p>"},{"location":"alternative-tools/leiningen/#install-leiningen","title":"Install Leiningen","text":"<p>Install the Leiningen tool using the specific instructions for your Operating System</p> <p>{% tabs first=\"Linux\", second=\"Homebrew\", third=\"GitBash\", forth=\"Chocolatey\", fifth=\"Windows Manual\" %}</p> LinuxHomebrewGitBashChocolateyWindows <p>Download the lein script to your local <code>bin</code> directory.  Then make the <code>lein</code> script executable and run <code>lein</code> to download the full version.</p> <p><pre><code>mkdir ~/bin\ncurl https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein &gt; ~/bin/lein\nchmod u+x ~/bin/lein\nlein\n</code></pre> If the command <code>lein</code> is not found, run <code>source ~/.bashrc</code> to ensure your <code>bin</code> directory is on the path.</p> <p>If you have Homebrew installed, run the following command in a terminal window.</p> <pre><code>brew install leiningen\n</code></pre> <p>GitBash allows you to use the Linux <code>lein</code> script, which may have less issues when installing.</p> <p>Create a directory called <code>C:\\Users\\your-user-name\\AppData\\Local\\Programs\\Leiningen</code></p> <p>Download the <code>lein</code> file and save it to the above directory</p> <p>Open <code>Environment variables for your account</code> and add the directory to your path</p> <p>Open a command window and run the command: <code>lein</code></p> <p>The full version of Leiningen will be downloaded and Leiningen is ready to use.</p> <p>If you have Chocolatey installed, add the Leiningen package by running the following command in a terminal window.</p> <pre><code>choco install lein\n</code></pre> <p>Create a directory called <code>C:\\Users\\your-user-name\\AppData\\Local\\Programs\\Leiningen</code></p> <p>Download the <code>lein.bat</code> file and save it to the above directory</p> <p>Open <code>Environment variables for your account</code> and add the directory to your path</p> <p>Open a command window and run the command: <code>lein.bat</code></p> <p>The full version of Leiningen will be downloaded and Leiningen is ready to use.</p>"},{"location":"alternative-tools/leiningen/#run-leiningen","title":"Run Leiningen","text":"<p>Check Leiningen is working by running <code>lein</code> command in a terminal</p> <pre><code>lein help\n</code></pre> <p>If a list of Leiningen commands is shown then it is working correctly.</p>"},{"location":"alternative-tools/leiningen/#create-project","title":"Create project","text":"<p>Create a new Clojure project with Leiningen using the <code>new</code> task</p> <pre><code>lein new template-name domain/project-name\n</code></pre> <p>Built-in templates include <code>app</code> and <code>lib</code></p> <p>Create a new project called playground</p> <p>Open a terminal window and in a directory where you usually keep your projects, run the following command <pre><code>lein new app practicalli/playground\n</code></pre> A new directory will be created called <code>playground</code> with a <code>src/practicalli/playground.clj</code></p>"},{"location":"alternative-tools/leiningen/#unit-testing","title":"Unit Testing","text":"<p>Leiningen automatically includes the <code>test</code> directory when running, so no additional configuration is required if all tests reside inside the <code>test</code> directory.</p> <p>Run all the tests saved to file:</p> <pre><code>lein test\n</code></pre> <p>Run just the unit tests in a specific namepsace.</p> <pre><code>lein test :only domain.namespace-test\n</code></pre>"},{"location":"alternative-tools/leiningen/#test-plugins","title":"Test Plugins","text":"<p>The following Leiningen plugins watch the file system and will run tests when a file change is detected in the project files.</p> <ul> <li>lein-test-refresh</li> <li>lein-auto</li> </ul>"},{"location":"alternative-tools/leiningen/#configure-test-paths","title":"Configure test paths","text":"<p><code>:test-paths</code> added as a top level key to the <code>defproject</code> configuration in the <code>project.clj</code> file will configure specific paths for tests</p> <p>For example, if the tests are defined under <code>project-name/clj/tests</code> then the project.clj file would look as follows:</p> <pre><code>(defproject my-project \"0.5.0-SNAPSHOT\"\n  :description \"A project for doing things.\"\n  :license \"Creative Commons Zero\"\n  :url \"http://github.com/practicalli/my-project\"\n\n  :dependencies [[org.clojure/clojure \"1.10.1\"]]\n  :test-paths   [\"clj/test\" \"src/test/clojure\"]\n  :plugins      [[lein-auto \"0.1.3\"]])\n</code></pre> <p><code>:source-paths</code> can also be used to define the location of the source code files in the same manner.</p>"},{"location":"assets/images/social/","title":"Social Cards","text":"<p>Social Cards are visual previews of the website that are included when sending links via social media platforms.</p> <p>Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in <code>mkdocs.yml</code></p> <p>Generated images are stored in this directory.</p>"},{"location":"automation/","title":"Automation","text":"<p>Automation tools can provide a consistent command line interface across a wide range of projects.</p> <p>Whilst the Clojure CLI is a very extensible tool that flexibility can also add some complexity to its command line interface.</p> <p>Automation tools abstract the command line to provide a consistent and simple user experience whilst keeping underlying flexibility.</p> <p>Practicalli recommends make</p> <p>A Makefile is not reliant on programming language knowledge so has no barrier to those who are unfamiliar with the Clojure language.</p> <p>Make is useful when working with mixed language teams to create a unified tool and command line across a wide range of projects.</p>"},{"location":"automation/#automation-tooling","title":"Automation tooling","text":"<ul> <li>Make - ubiquitous task automation tool, programming language agnostic</li> <li>Shell Scripts</li> <li>Babashka - create task automation tool with Clojure</li> </ul>"},{"location":"automation/#make","title":"Make","text":"<p>Make is very simple to use and has a long history as a build tool and wider task automation tool.</p> <p>Task are defined in a <code>Makefile</code> and task can depend on each other. Any commands or combination of commands that run on the command line can be used as make tasks.</p> <p>make provides tab completion of tasks defined in the Makefile without additional configuration.</p> <p><code>make</code> is available for all operating systems.</p> <p>Practicalli Project Templates include Makefile</p> <p>Creating new projects with <code>:project/create</code> and Practicalli Project Templates provide a Makefile with a wide range of common tasks for Clojure development. </p>"},{"location":"automation/#shell-scripts","title":"Shell Scripts","text":"<p>Shell scripts provide a very common way to create a relatively ubiquitous approach to running tools, even across multiple Shell implementations (Bash, Zsh, fish, etc.) and operating systems.</p> <p>Shell scripting language is very powerful especially for manipulation of the operating system, although scripts require development and maintenance.</p>"},{"location":"automation/#babashka","title":"Babashka","text":"<p>Write automation scripts with Clojure code using the Babashka task runner</p> <p>Babashka can use a wide range of Clojure functions and libraries, although as a general script tool then additional coding and maintenance may be reqiured compared to a dedicated tool.</p> <p>Babashka task runner</p>"},{"location":"automation/make/","title":"Make","text":"<p> practicalli/dotfiles Makefile</p> <p>GNU Make provide a simple and consistent way to run any development task for Clojure &amp; ClojureScript projects (or any other languages).</p> <p>Wrap any combination of tools (building, linting, formatting, testing) with Make targets for a simple command line interface.</p> <p>Make supports tab completion making tasks discoverable.</p> <p>All that is required is a <code>Makefile</code> in the root of the project</p>"},{"location":"automation/make/#gnu-make-overview","title":"GNU Make overview","text":"<p>GNU Make is a language agnostic build automation tool which has been an integral part of building Linux/Unix operating system code and applications for decades, providing a consistent way to configure, compile and deploy code for all projects.</p> <p>A <code>Makefile</code> defines targets called via the <code>make</code> command. Each target can run one or more commands.  Targets can be dependent on other targets,  e.g the <code>dist</code> target that builds a project can be dependent on <code>deps</code> &amp; <code>test</code> targets.</p> <p>GNU Make is available on all Linux/Unix based operating systems (and Windows via chocolatey or nmake).</p> <p>Practicalli also uses <code>make</code> to configure and build the latest versions of Emacs and other Linux open source software</p>"},{"location":"automation/make/#defining-tasks","title":"Defining tasks","text":"<p>Create a <code>Makefile</code> in the root of a project and define a target by typing a suitable name followed by a <code>:</code> character, e.g. <code>test:</code></p> <p>Insert a tab on the next line and type a command to be called.  Further commands can be added on new lines so long as each line is tab indented.</p> <p>The <code>repl</code> target prints out an information message and then uses the Clojure CLI with aliases from practicalli/clojure-deps-edn to run a Clojure REPL process with a rich terminal UI (Rebel Readline)</p> <pre><code>repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:dev/env:test/env:repl/rebel\n</code></pre>"},{"location":"automation/make/#common-target-naming","title":"Common target naming","text":"<p>Targets used across Practicalli projects follow the make standard targets for users</p> <p><code>all</code> , <code>test-ci</code> , <code>deps</code> and <code>dist</code> targets are recommended for use with a CI deployment pipeline and builder stage when using Docker.</p> <ul> <li><code>all</code>  calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean</li> <li><code>deps</code> download library dependencies (depend on <code>deps.edn</code> file)</li> <li><code>dist</code> create a distribution tar file for this program or zip deployment package for AWS Lambda</li> <li><code>lint</code> run lint tools to check code quality  - e.g MegaLinter which provides a wide range of tools</li> <li><code>format-check</code> report format and style issues for a specific programming language</li> <li><code>format-fix</code> update source code files if there are format and style issues for a specific programming language</li> <li><code>pre-commit</code> run unit tests and code quality targets before considering a Git commit</li> <li><code>repl</code> run an interactive run-time environment for the programming language</li> <li><code>test-unit</code> run all unit tests</li> <li><code>test-ci</code> test running in CI build (optionally focus on integration testing)</li> <li><code>clean</code> remove files created by any of the commands from other targets (i.e. ensure a clean build each time)</li> </ul> <p>practicalli/dotfiles/Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.</p>"},{"location":"automation/make/#target-dependencies","title":"Target dependencies","text":"<p>A <code>Makefile</code> target can depend on either a file name or another target in the <code>Makefile</code>.</p> <p>The all target typically depends on several <code>Makefile</code> targets to test, compile and package a service.  Add the names of the targets this target depends upon</p> <pre><code>all: deps test-ci dist clean\n</code></pre> <p>Add the filename of a file after the name of the target, to depend on if that file has changed.  If the file has not changed since make was last run then the task will not run again.</p> <p>Clojure CLI Example: If the <code>deps</code> target depends on <code>deps.edn</code> and the file has not changed since last run, the deps target will not run again.</p>"},{"location":"automation/make/#deps-target-depend-on-a-file","title":"deps target - depend on a file","text":"<p>The deps target would use Clojure CLI or Leiningen to download dependencies.</p> <p>Configuring the <code>deps</code> target to depend on <code>deps.edn</code> or <code>project.clj</code> file, then if the file has not changed the deps will not run again.</p> <p>A Clojure CLI example depends on the <code>deps.edn</code> file that defines all the library dependencies for the project, tools for testing and packaging the Clojure service.  The <code>-P</code> flag is the prepare option, a dry run that only downloads the dependencies for the given tasks.</p> <pre><code>deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download libraries to test and build the service ---------)\n    clojure -P -X:test/env:package/uberjar\n</code></pre> <p><code>:test/env</code> adds libraries to run Kaocha and libraries used to run unit tests.  <code>:package/uberjar</code> runs a tool that creates an uberjar.</p>"},{"location":"automation/make/#clean-target-hiding-command-errors","title":"Clean target - hiding command errors","text":"<p>The clean target should remove files and directories created by the build (compile) process, to ensure a consistent approach to building each time.</p> <p>On Linux / Unix systems files can be deleted with the <code>rm</code> command using <code>-r</code> for recursively deleting a directory and its contents. <code>-f</code> forces the deleting of files and directories, otherwise a prompt for confirmation of the delete may be shown.</p> <p><code>-</code> before a command  instructs <code>make</code> to ignore an error code, useful if the files to be deleted did not exist (i.e. the build failed part way through and not all files were created).</p> <pre><code># `-` before the command ignores any errors returned\nclean:\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n</code></pre>"},{"location":"automation/make/#megalinter-target-simplifying-a-command","title":"MegaLinter target - simplifying a command","text":"<p>The <code>lint</code> target is an example of how the <code>Makefile</code> simplifies the command line interface.</p> <p><code>lint:</code> target is used to call the MegaLinter runner, avoiding the need to remember the common options passed when calling MegaLinter command line tool, <code>mega-linter-runner</code></p> <p>The Java flavor of MegaLinter is less than 2Gb image (full MegaLinter image is 8Gb) and contains all the tools for a Clojure project.  The flavor can only be set via a command line option, so the make file ensures that option is always used and the full MegaLinter docker image is not downloaded by mistake.</p> <p>When MegaLinter is configured to generate reports (default), <code>lint-clean:</code> target is used to clean those reports.</p> <pre><code># Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n\nlint-clean:\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n</code></pre>"},{"location":"automation/make/#enhancing-make-output","title":"Enhancing make output","text":"<p>The <code>info</code> message is used with each target to enhances the readability of the make output, especially when multiple targets and commands are involved, or if commands are generating excessive output to standard out.</p> <pre><code> test:\n    $(info --------- Runner for unit tests ---------)\n    ./bin/test\n</code></pre> <p></p>"},{"location":"automation/make/#avoiding-file-name-collisions","title":"Avoiding file name collisions","text":"<p>Although unlikely, if a filename in the root of a project has the same name as a <code>Makefile</code> target, it can be used instead of running the targets command</p> <p><code>.PHONY:</code> defines the names of targets in the <code>Makefile</code> to avoid name clashes</p> <pre><code>.PHONY: all lint deps test test-ci dist clean\n</code></pre> <p>phony - MakefileTutorial</p>"},{"location":"automation/make/#halt-on-error","title":"Halt on error","text":"<p><code>.DELETE_ON_ERROR:</code> halts any further commands if a command returns non-zero exit status.  Useful as short-circuit to stop tasks when further work is not valuable, e.g. if tests fail then it may not be valuable to build the Clojure project.</p> <pre><code>.DELETE_ON_ERROR:\nall: deps test-ci dist clean\n</code></pre> <p>delete_on_error - MakefileTutorial</p>"},{"location":"automation/make/#references","title":"References","text":"<p>Makefile Tutorial by Example practicalli/dotfiles Makefile</p>"},{"location":"automation/make/#summary","title":"Summary","text":"<p>A <code>Makefile</code> can simplify the command line interface for any task with a Clojure project (or any other language and tooling).</p> <p>Using the same target names across all projects reduces the cognitive load for driving any project.</p>"},{"location":"clojure-cli/","title":"Clojure CLI","text":"Learn by doing <p>To learn Clojure CLI by doing, jump to Terminal REPL or Clojure project sections to start using the Clojure CLI</p> <p>Clojure CLI (command line interface) is the latest approach to working with Clojure projects, libraries and tools. Clojure CLI focuses on:</p> <ul> <li>running Clojure code (applications and tools)</li> <li>starting a REPL process (Read-Eval-Print Loop) for interactive development with a Clojure editor or a command line REPL UI.</li> <li>managing dependencies (tools.deps) -downloading from Maven and Git repositories</li> <li>building Clojure projects (using tools.build) to create deployable Clojure services</li> </ul> <p> Practicalli Clojure CLI Config extends the feautres of Clojure CLI, defining aliases that add community libraries and tools.</p> <p> </p> Video commands dated but concepts remain valid"},{"location":"clojure-cli/#common-tasks-for-clojure-development","title":"Common tasks for Clojure development","text":"<p>The Clojure CLI has several built-in tasks.  Additional tasks are provided via aliases that include libraries and tools from the Clojure community, e.g.  Practicalli Clojure CLI Config</p> <p>REPL Reloaded</p> <p><code>clojure -M:repl/reloaded</code> runs a rich terminal UI REPL prompt that includes portal data inspector, namespace reloading and library hotload tools. <code>test</code> path is included to support editor test runners and <code>dev</code> path for custom user namespace for custom REPL startup</p> Task Command Defined In Basic terminal UI REPL <code>clojure</code> (or <code>clj</code> if <code>rlwrap</code> binary installed) Clojure CLI Enhanced terminal UI REPL (Rebel &amp; nREPL) <code>clojure -M:repl/rebel</code> or <code>clojure -M:repl/reloaded</code> Practicalli Create project <code>clojure -T:project/new :template app :name domain/appname :args '[\"+h2\"]'</code> Practicalli Run unit tests / watch for changes <code>clojure -X:test/run</code> or <code>clojure -X:test/watch</code> Practicalli Run the project (clojure.main) <code>clojure -M -m domain.main-namespace</code> No Alias Find libraries (maven &amp; git) <code>clojure -M:search/library library-name</code> Practicalli Find library versions (maven) <code>clojure -X:deps find-versions domain/library-name</code> CLojure CLI Download dependencies <code>clojure -P</code>  (plus optional execution flags with aliases) CLojure CLI Check for new dependency versions <code>clojure -T:search/outdated</code> Practicalli Package library <code>clojure -X:build/jar</code> and <code>clojure -X:build/uberjar</code> Practicalli Deploy library locally <code>clojure -X:deps mvn-install</code> Clojure CLI Check code for unused vars <code>clojure -X:search/unused</code> Practicalli <p>tools.build is recommended for packaging projects</p> <p>Package with tools.build is the recommended approach to create jar and Uberjar packages of a Clojure project.</p>"},{"location":"clojure-cli/#execution-option-flags","title":"Execution option flags","text":"<p>The execution option flags for the <code>clojure</code> command define how to run Clojure code.  The most commonly used options are:</p> <ul> <li><code>-M</code> uses clojure.main and calls the <code>-main</code> function of the given namespace, passing positional string arguments.</li> <li><code>-X</code> uses clojure.exec to call a fully qualified function which has a map argument, passing key/value pair arguments. <code>-T</code> is the same as <code>-X</code> execpt setting the classpath to <code>.</code>, ignoring project dependencies not defined in a given alias.</li> </ul> Flag Purpose <code>-A</code> Pass alias to built-in terminal UI REPL (<code>clojure</code> or <code>clj</code>) <code>-M</code> Run Clojure with clojure.main <code>-P</code> Prepare / dry run (Build scripts, CI servers, Containers) <code>-X</code> Execute a fully qualified function, optional default arguments <code>-T</code> Run a tool independently from a project configuration <code>-J</code> Java Virtual Machine specific options (heap size, etc) <p>Examples of execution option flags</p> <p>Execution option page expands on flag usage with numerous examples</p>"},{"location":"clojure-cli/#configure-clojure-cli","title":"Configure Clojure CLI","text":"<p>A <code>deps.edn</code> file configures the Clojure CLI, using extensible data notation (EDN), the underlying syntax of Clojure itself.</p> <p>Configuration is defined using a hash-map with the following top-level keys:</p> <ul> <li><code>:deps</code> - library dependencies</li> <li><code>:paths</code> - directories to search for code and resources (Java classpath)</li> <li><code>:aliases</code> - named configuration defining extra paths, extra deps and configuration to run Clojure</li> <li><code>:mvn/repos</code> - library dependency sources, remote and local (e.g. Clojars, Maven, Artifactory, etc).</li> </ul> <p><code>:aliases</code> configuration is only included when using the alias name with the Clojure CLI, e.g. <code>:repl/rebel</code> alias in  Practicalli Clojure CLI Config adds library dependencies only used during development to run a rich terminal UI REPL.</p> <pre><code>clojure -M:repl/rebel\n</code></pre> Add a wide range of aliases by installing  Practicalli Clojure CLI Config <p> Practicalli Clojure CLI Config provides aliases for a wide range of tools for use with Clojure CLI to support Clojure software development.</p>"},{"location":"clojure-cli/#precedence-order","title":"Precedence Order","text":"<p>Clojure CLI Configuration can be used from several different sources.</p> Configuration Description Command line arguments string or edn (key value) arguments passed to the <code>clojure</code> command project <code>deps.edn</code> Project specific configuration: paths, dependencies, aliases <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> / <code>$HOME/.clojure/deps.edn</code> User level configuration for use with all projects Clojure CLI install Includes Clojure standard library, <code>src</code> path and built-in <code>:deps</code> aliases <p></p> <p>Command line arguments take preceedence over the other configurations. When running the <code>clojure</code> command the configurations are merged, with key/values being added or replaces following the precedence order.</p>"},{"location":"clojure-cli/#install-configuration","title":"Install configuration","text":"<p>Clojure CLI install has a built-in configuration:</p> <ul> <li><code>org.clojure/clojure</code> library dependency, setting the default version of Clojure for the Clojure CLI</li> <li><code>src</code> set as the default path</li> </ul> Clojure CLI Install deps.edn <p>The Clojure CLI install includes a <code>deps.edn</code> configuration, e.g. <code>/usr/local/lib/clojure/deps.edn</code> <pre><code>{\n  :paths [\"src\"]\n\n  :deps {\n    org.clojure/clojure {:mvn/version \"1.11.1\"}\n  }\n\n  :aliases {\n    :deps {:replace-paths []\n           :replace-deps {org.clojure/tools.deps.cli {:mvn/version \"0.9.10\"}}\n           :ns-default clojure.tools.deps.cli.api\n           :ns-aliases {help clojure.tools.deps.cli.help}}\n    :test {:extra-paths [\"test\"]}\n  }\n\n  :mvn/repos {\n    \"central\" {:url \"https://repo1.maven.org/maven2/\"}\n    \"clojars\" {:url \"https://repo.clojars.org/\"}\n  }\n}\n</code></pre></p> Check version of Clojure <p>Evaluate <code>*clojure-version*</code> in a REPL shows which version of the Clojure language is currently being used.</p> <p>Including <code>org.clojure/clojure</code> as a dependency the project <code>deps.edn</code> file specifies a version of the Clojure language.  The Clojure CLI version is used if no other dependency is specified.</p>"},{"location":"clojure-cli/#user-configuration","title":"User configuration","text":"<p>A Clojure CLI user configuration is available to all projects by the operating system user account.   Practicalli Clojure CLI Config is a user configuration that contains a set of well-formed aliases that add common tools for all Clojure project.</p> Clojure CLI User Configuration Location <p>Clojure CLI tools creates a configuration directory called <code>.clojure</code>, which by default is placed in the root of the operating system user account directory, e.g. <code>$HOME/.clojure</code>.</p> <p><code>XDG_CONFIG_HOME</code> may be set by your operating system and over-rides the default location, e.g. <code>$HOME/.config/.clojure</code></p> <p><code>CLJ_CONFIG</code> can be used to over-ride all other location settings</p> <p>Run <code>clojure -Sdescribe</code> in a terminal and checking the <code>:config-user</code> value to see the location of your Clojure configuration directory</p> <p>A basic example of a user configuration for Clojure CLI</p> <pre><code>{\n  :aliases {\n    :test/env {:extra-paths [\"test\"]}\n\n    :project/new\n    {:extra-deps {seancorfield/clj-new {:mvn/version \"1.0.199\"}}\n     :main-opts  [\"-m\" \"clj-new.create\"]}\n  }\n\n  :mvn/repos {\n    \"central\" {:url \"https://repo1.maven.org/maven2/\"}\n    \"clojars\" {:url \"https://repo.clojars.org/\"}\n  }\n}\n</code></pre> <p>Clojure Tools install sets Clojure version</p> <p>A default version of Clojure is set by the Clojure tools install, enabling the <code>clojure</code> command to know what version of Clojure library to use.  This version will be over-ridden by the user or project specific deps.edn configuration files if set.</p>"},{"location":"clojure-cli/#references","title":"References","text":"<p>tools.deps and cli guide clojure.main API Reference tools.deps.alpha API Reference</p>"},{"location":"clojure-cli/built-in-commands/","title":"Clojure CLI Built-in commands","text":"<p><code>clojure</code> without any other arguments will run a REPL with a basic terminal prompt.  </p> <p><code>clj</code> is a wrapper script for the <code>clojure</code> command (<code>rlwrap</code> required) to add command history to the basic REPL prompt.</p> <p><code>clojure -T:deps</code> to run one of several built-in commands to help work with Clojure CLI projects and libraries.</p> <p><code>clojure --help</code> list the available commands.</p>"},{"location":"clojure-cli/built-in-commands/#deps-tool","title":":deps tool","text":"<p>The <code>:deps</code> aliases provides tools for managing library dependencies.  </p> <p>The Clojure CLI <code>-X</code> flag is used to call these tools via <code>clojure.exec</code> and take key value pairs as arguments</p> aliases Description <code>clojure -X:deps list</code> List full transitive deps set and licenses <code>clojure -X:deps tree</code> download dependencies &amp; print dependency tree, indenting libraries that are dependencies of dependencies <code>clojure -X:deps find-versions</code> Find available versions of a given library (domain/name) <code>clojure -X:deps prep</code> Prepare all unprepped libs in the dep tree <code>clojure -X:deps mvn-pom</code> Generate or update pom.xml with deps and paths <code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'</code> install a given jar file into the local maven repository, eg. <code>~/.m2/repository</code> <code>clojure -X:deps git-resolve-tags</code> update <code>deps.edn</code> git based dependencies that used tags with the equivalent SHA commit values <p>tools.deps.alpha API Reference</p> <p>Libraries are downloaded if they are not in the local Maven cache, e.g. <code>$HOME/.m2/repository</code>, so on first run a command may take a little time.</p> Use Clojure CLI -P flag to download libraries <p><code>clojure -P</code> is the recommended way to download library dependencies as it does not run any other commands</p> <p>The <code>-P</code> flag can be used with aliases to download libraries for building and testing a Clojure project, especially useful for a cached environment like Docker.</p> <pre><code>clojure -P -M:dev/reloaded:project/build\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#list-library-dependencies","title":"List Library dependencies","text":"<p>List library depenencies of a project, including the library version and software licence for each library.</p> <p>The list includes transitive dependencies, library dependencies of the project library dependencies.</p> <p>The <code>:aliases '[:alias/name(s)]'</code> argument will also list library dependencies from a given alias, either project alias or user alias. </p> <pre><code>clojure -X:deps list\n</code></pre> Dependency list from Practicalli Service project template <pre><code> \u276f clojure -X:deps list\naero/aero 1.1.6  (MIT)\namalloy/ring-buffer 1.3.1  (EPL-1.0)\naysylu/loom 1.0.2  (EPL-1.0)\nborkdude/dynaload 0.2.2  (EPL-1.0)\nborkdude/edamame 0.0.18  (EPL-1.0)\ncom.bhauman/spell-spec 0.1.2  (EPL-1.0)\ncom.brunobonacci/mulog 0.9.0  (Apache-2.0)\ncom.brunobonacci/mulog-adv-console 0.9.0  (Apache-2.0)\ncom.brunobonacci/mulog-json 0.9.0  (Apache-2.0)\ncom.cnuernber/charred 1.010\ncom.cognitect/transit-clj 1.0.324  (Apache-2.0)\ncom.cognitect/transit-java 1.0.343  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-annotations 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-core 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-databind 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.datatype/jackson-datatype-jsr310 2.12.0  (Apache-2.0)\ncom.google.javascript/closure-compiler v20151015  (Apache-2.0)\ncom.googlecode.json-simple/json-simple 1.1.1  (Apache-2.0)\ncommons-codec/commons-codec 1.15  (Apache-2.0)\ncommons-fileupload/commons-fileupload 1.4  (Apache-2.0)\ncommons-io/commons-io 2.6  (Apache-2.0)\ncrypto-equality/crypto-equality 1.0.0  (EPL-1.0)\ncrypto-random/crypto-random 1.2.0  (EPL-1.0)\nexpound/expound 0.9.0  (EPL-1.0)\nfipp/fipp 0.6.25  (EPL-1.0)\nhttp-kit/http-kit 2.6.0  (Apache-2.0)\njavax.xml.bind/jaxb-api 2.3.0  (CDDL 1.1)\nlambdaisland/deep-diff 0.0-47  (EPL-1.0)\nmeta-merge/meta-merge 1.0.0  (EPL-1.0)\nmetosin/jsonista 0.3.1  (EPL-1.0)\nmetosin/malli 0.7.5  (EPL-2.0)\nmetosin/muuntaja 0.6.8  (EPL-1.0)\nmetosin/reitit 0.5.13  (EPL-1.0)\nmetosin/reitit-core 0.5.18  (EPL-1.0)\nmetosin/reitit-dev 0.5.18  (EPL-1.0)\nmetosin/reitit-frontend 0.5.13  (EPL-1.0)\nmetosin/reitit-http 0.5.13  (EPL-1.0)\nmetosin/reitit-interceptors 0.5.13  (EPL-1.0)\nmetosin/reitit-malli 0.5.13  (EPL-1.0)\nmetosin/reitit-middleware 0.5.13  (EPL-1.0)\nmetosin/reitit-ring 0.5.13  (EPL-1.0)\nmetosin/reitit-schema 0.5.13  (EPL-1.0)\nmetosin/reitit-sieppari 0.5.13  (EPL-1.0)\nmetosin/reitit-spec 0.5.13  (EPL-1.0)\nmetosin/reitit-swagger 0.5.13  (EPL-1.0)\nmetosin/reitit-swagger-ui 0.5.13  (EPL-1.0)\nmetosin/ring-swagger-ui 3.36.0  (EPL-1.0)\nmetosin/schema-tools 0.12.3  (EPL-1.0)\nmetosin/sieppari 0.0.0-alpha13  (EPL-1.0)\nmetosin/spec-tools 0.10.5  (EPL-1.0)\nmvxcvi/arrangement 2.0.0  (Public Domain)\nmvxcvi/puget 1.1.2  (Public Domain)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/clojurescript 1.7.170  (EPL-1.0)\norg.clojure/core.rrb-vector 0.0.14  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 0.2.6  (EPL-1.0)\norg.clojure/data.priority-map 0.0.5  (EPL-1.0)\norg.clojure/google-closure-library 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/google-closure-library-third-party 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/java.classpath 1.0.0  (EPL-1.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/test.check 1.1.1  (EPL-1.0)\norg.clojure/tools.namespace 1.3.0  (EPL-1.0)\norg.clojure/tools.reader 1.3.6  (EPL-1.0)\norg.javassist/javassist 3.18.1-GA  (MPL 1.1)\norg.mozilla/rhino 1.7R5  (Mozilla Public License, Version 2.0)\norg.msgpack/msgpack 0.6.12  (Apache-2.0)\nparty.donut/system 0.0.202 \nprismatic/schema 1.1.12  (EPL-1.0)\nring/ring-codec 1.1.3  (MIT)\nring/ring-core 1.9.1  (MIT)\ntailrecursion/cljs-priority-map 1.2.1  (EPL-1.0)\ntech.droit/clj-diff 1.0.1  (EPL-1.0)\n</code></pre> <p>Use the <code>:aliases '[:alias/name(s)]'</code> option to also include the dependencies from a project or user alias.  Showing the dependencies from an aliase can useful to identify conflicting dependencies when using an alias (unlikely but it could happen).</p> <pre><code>clojure -X:deps list :aliases '[:dev/reloaded]'\n</code></pre> Dependency list from project and Practicalli :dev/reloaded alias <pre><code>\u276f clojure -X:deps list :aliases '[:dev/reloaded]'\naero/aero 1.1.6  (MIT)\namalloy/ring-buffer 1.3.1  (EPL-1.0)\nclj-commons/clj-yaml 1.0.27  (EPL-1.0)\ncom.brunobonacci/mulog 0.9.0  (Apache-2.0)\ncom.cognitect/transit-clj 1.0.333  (Apache-2.0)\ncom.cognitect/transit-cljs 0.8.280  (Apache-2.0)\ncom.cognitect/transit-java 1.0.371  (Apache-2.0)\ncom.cognitect/transit-js 0.8.874  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-core 2.14.2  (Apache-2.0)\ncom.google.code.gson/gson 2.10.1  (Apache-2.0)\ncom.googlecode.json-simple/json-simple 1.1.1  (Apache-2.0)\ncom.nextjournal/beholder 1.0.2 \ncriterium/criterium 0.4.6  (EPL-1.0)\ndjblue/portal 0.49.0  (MIT)\nexpound/expound 0.9.0  (EPL-1.0)\nfipp/fipp 0.6.26  (EPL-1.0)\nhawk/hawk 0.2.11  (EPL-1.0)\nhttp-kit/http-kit 2.7.0  (Apache-2.0)\nio.methvin/directory-watcher 0.17.3  (Apache-2.0)\njavax.activation/javax.activation-api 1.2.0  (CDDL/GPLv2+CE)\njavax.xml.bind/jaxb-api 2.4.0-b180830.0359  (CDDL 1.1)\nlambdaisland/clj-diff 1.4.78  (EPL-1.0)\nlambdaisland/deep-diff2 2.10.211  (EPL-1.0)\nlambdaisland/kaocha 1.87.1366  (EPL-1.0)\nlambdaisland/tools.namespace 0.3.256  (EPL-1.0)\nmeta-merge/meta-merge 1.0.0  (EPL-1.0)\nmvxcvi/arrangement 2.1.0  (Public Domain)\nnet.incongru.watchservice/barbary-watchservice 1.0  (GPLv2 + Classpath Exception)\nnet.java.dev.jna/jna 5.12.1  (LGPL-2.1-or-later)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/core.rrb-vector 0.1.2  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 2.4.0  (EPL-1.0)\norg.clojure/java.classpath 1.0.0  (EPL-1.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/test.check 1.1.1  (EPL-1.0)\norg.clojure/tools.cli 1.0.219  (EPL-1.0)\norg.clojure/tools.namespace 1.4.4  (EPL-1.0)\norg.clojure/tools.reader 1.3.6  (EPL-1.0)\norg.clojure/tools.trace 0.7.11  (EPL-1.0)\norg.flatland/ordered 1.15.11  (EPL-1.0)\norg.javassist/javassist 3.18.1-GA  (MPL 1.1)\norg.msgpack/msgpack 0.6.12  (Apache-2.0)\norg.slf4j/slf4j-api 2.0.9  (MIT)\norg.slf4j/slf4j-nop 2.0.9  (MIT)\norg.tcrawley/dynapath 1.1.0  (EPL-1.0)\norg.yaml/snakeyaml 2.1  (Apache-2.0)\nprogrock/progrock 0.1.2  (EPL-1.0)\nslingshot/slingshot 0.12.2  (EPL-1.0)\n</code></pre> <p>The <code>:aliases</code> option can be used to inspect the dependencies of a user alias, listing only dependencies from the specified aliases when run outside of a Clojure project.</p> Dependency list from Practicalli :repl/rebel alias only <pre><code>\u276f clojure -X:deps list :aliases '[:repl/rebel]'\ncider/cider-nrepl 0.42.1  (EPL-1.0)\ncider/orchard 0.18.0  (EPL-1.0)\ncljfmt/cljfmt 0.5.7  (EPL-1.0)\ncom.bhauman/rebel-readline 0.1.4  (EPL-1.0)\ncom.google.javascript/closure-compiler v20151216  (Apache-2.0)\ncompliment/compliment 0.3.6  (EPL-1.0)\nmx.cider/logjam 0.1.1  (EPL-1.0)\nnrepl/nrepl 1.1.0  (EPL-1.0)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/clojurescript 1.7.228  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 0.2.6  (EPL-1.0)\norg.clojure/google-closure-library 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/google-closure-library-third-party 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/tools.reader 1.0.0-alpha4  (EPL-1.0)\norg.fusesource.jansi/jansi 1.16  (Apache-2.0)\norg.jline/jline-reader 3.5.1  (The BSD License)\norg.jline/jline-terminal 3.5.1  (The BSD License)\norg.jline/jline-terminal-jansi 3.5.1  (The BSD License)\norg.mozilla/rhino 1.7R5  (Mozilla Public License, Version 2.0)\nrewrite-clj/rewrite-clj 0.5.2  (MIT)\nrewrite-cljs/rewrite-cljs 0.4.3  (MIT)\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#dependency-tree","title":"Dependency tree","text":"<p>Show a tree hieracthy of project library dependencies, including the library name and version used.</p> <p>The tree includes transitive dependencies, library dependencies of the project library dependencies.</p> <p>The <code>:aliases '[:alias/name(s)]'</code> argument will also list library dependencies from a given alias, either project alias or user alias. </p> <pre><code>clojure -X:deps tree\n</code></pre> Dependency list from Practicalli Service project template <pre><code>\u276f clojure -X:deps tree\norg.clojure/clojure 1.11.1\n  . org.clojure/spec.alpha 0.3.218\n  . org.clojure/core.specs.alpha 0.2.62\nhttp-kit/http-kit 2.6.0\nmetosin/reitit 0.5.13\n  X metosin/reitit-core 0.5.13 :superseded\n    X meta-merge/meta-merge 1.0.0 :parent-omitted\n  X metosin/reitit-dev 0.5.13 :use-top\n  . metosin/reitit-spec 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/spec-tools 0.10.5\n      X org.clojure/spec.alpha 0.2.187 :older-version\n  . metosin/reitit-malli 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    X metosin/malli 0.3.0 :older-version\n  . metosin/reitit-schema 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/schema-tools 0.12.3\n      . prismatic/schema 1.1.12\n  . metosin/reitit-ring 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . ring/ring-core 1.9.1\n      . ring/ring-codec 1.1.3\n        . commons-codec/commons-codec 1.15\n      . commons-io/commons-io 2.6\n      . commons-fileupload/commons-fileupload 1.4\n        X commons-io/commons-io 2.2 :older-version\n      . crypto-random/crypto-random 1.2.0\n        X commons-codec/commons-codec 1.6 :older-version\n      . crypto-equality/crypto-equality 1.0.0\n  . metosin/reitit-middleware 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . lambdaisland/deep-diff 0.0-47\n      . mvxcvi/puget 1.1.2\n        X mvxcvi/arrangement 1.2.0 :older-version\n        X fipp/fipp 0.6.17 :older-version\n      X fipp/fipp 0.6.17 :older-version\n      . org.clojure/core.rrb-vector 0.0.14\n      . tech.droit/clj-diff 1.0.1\n      X mvxcvi/arrangement 1.2.0 :older-version\n    . metosin/muuntaja 0.6.8\n      . metosin/jsonista 0.3.1\n      . com.cognitect/transit-clj 1.0.324\n        . com.cognitect/transit-java 1.0.343\n          X com.fasterxml.jackson.core/jackson-core 2.8.7 :older-version\n          . org.msgpack/msgpack 0.6.12\n            . com.googlecode.json-simple/json-simple 1.1.1\n            . org.javassist/javassist 3.18.1-GA\n          X commons-codec/commons-codec 1.10 :older-version\n          . javax.xml.bind/jaxb-api 2.3.0\n    . metosin/spec-tools 0.10.5\n  . metosin/reitit-http 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/reitit-ring 0.5.13\n  . metosin/reitit-interceptors 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . lambdaisland/deep-diff 0.0-47\n    . metosin/muuntaja 0.6.8\n  . metosin/reitit-swagger 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n  . metosin/reitit-swagger-ui 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . metosin/jsonista 0.3.1\n      X com.fasterxml.jackson.core/jackson-core 2.12.0 :older-version\n      X com.fasterxml.jackson.core/jackson-databind 2.12.0 :older-version\n      . com.fasterxml.jackson.datatype/jackson-datatype-jsr310 2.12.0\n        X com.fasterxml.jackson.core/jackson-annotations 2.12.0 :older-version\n        X com.fasterxml.jackson.core/jackson-core 2.12.0 :older-version\n        X com.fasterxml.jackson.core/jackson-databind 2.12.0 :older-version\n    . metosin/ring-swagger-ui 3.36.0\n  . metosin/reitit-frontend 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n  . metosin/reitit-sieppari 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/sieppari 0.0.0-alpha13\n  . com.fasterxml.jackson.core/jackson-core 2.12.1\n  . com.fasterxml.jackson.core/jackson-databind 2.12.1\n    . com.fasterxml.jackson.core/jackson-annotations 2.12.1\n    . com.fasterxml.jackson.core/jackson-core 2.12.1\nmetosin/reitit-dev 0.5.18\n  . metosin/reitit-core 0.5.18 :newer-version\n    . meta-merge/meta-merge 1.0.0\n  . com.bhauman/spell-spec 0.1.2\n  . expound/expound 0.9.0\n  . fipp/fipp 0.6.25\ncom.brunobonacci/mulog 0.9.0\n  . amalloy/ring-buffer 1.3.1\ncom.brunobonacci/mulog-adv-console 0.9.0\n  X com.brunobonacci/mulog 0.9.0 :use-top\n  . com.brunobonacci/mulog-json 0.9.0\n    X com.brunobonacci/mulog 0.9.0 :use-top\n    . com.cnuernber/charred 1.010\naero/aero 1.1.6\nparty.donut/system 0.0.202\n  . aysylu/loom 1.0.2\n    . org.clojure/data.priority-map 0.0.5\n    . tailrecursion/cljs-priority-map 1.2.1\n      . org.clojure/clojurescript 1.7.170\n        . com.google.javascript/closure-compiler v20151015\n        . org.clojure/google-closure-library 0.0-20151016-61277aea\n          . org.clojure/google-closure-library-third-party 0.0-20151016-61277aea\n        . org.clojure/data.json 0.2.6\n        . org.mozilla/rhino 1.7R5\n        X org.clojure/tools.reader 0.10.0-alpha3 :older-version\n  . org.clojure/tools.namespace 1.3.0\n    . org.clojure/java.classpath 1.0.0\n    . org.clojure/tools.reader 1.3.6\n  . metosin/malli 0.7.5\n    . borkdude/dynaload 0.2.2\n    . borkdude/edamame 0.0.18\n      X org.clojure/tools.reader 1.3.4 :older-version\n    . org.clojure/test.check 1.1.1\n    X fipp/fipp 0.6.24 :older-version\n    . mvxcvi/arrangement 2.0.0\n</code></pre> <p>Use the <code>:aliases</code> option with the Clojure CLI in the root of a project to show library dependencies for the project and the <code>:dev/reloaded</code> alias which could be useful if there are library conflicts when using an alias (unlikely but it could happen).</p> <pre><code>clojure -X:deps tree :aliases '[:dev/reloaded]'\n</code></pre> <p>The <code>:aliases</code> option can be used to inspect the dependencies of a user alias, listing only dependencies from the specified aliases when run outside of a Clojure project.</p> Dependency list from Practicalli :repl/rebel alias only <pre><code> \u276f clojure -X:deps tree :aliases '[:repl/rebel]'\norg.clojure/clojure 1.11.1\n  . org.clojure/spec.alpha 0.3.218\n  . org.clojure/core.specs.alpha 0.2.62\nnrepl/nrepl 1.1.0\ncider/cider-nrepl 0.42.1\n  X nrepl/nrepl 1.0.0 :use-top\n  . cider/orchard 0.18.0\n  . mx.cider/logjam 0.1.1\ncom.bhauman/rebel-readline 0.1.4\n  . org.jline/jline-reader 3.5.1\n    . org.jline/jline-terminal 3.5.1\n  . org.jline/jline-terminal 3.5.1\n  . org.jline/jline-terminal-jansi 3.5.1\n    . org.fusesource.jansi/jansi 1.16\n    . org.jline/jline-terminal 3.5.1\n  . cljfmt/cljfmt 0.5.7\n    . org.clojure/tools.reader 1.0.0-alpha4\n    . rewrite-clj/rewrite-clj 0.5.2\n      X org.clojure/tools.reader 0.10.0 :older-version\n    . rewrite-cljs/rewrite-cljs 0.4.3\n      . org.clojure/clojurescript 1.7.228\n        . com.google.javascript/closure-compiler v20151216\n        . org.clojure/google-closure-library 0.0-20151016-61277aea\n          . org.clojure/google-closure-library-third-party 0.0-20151016-61277aea\n        . org.clojure/data.json 0.2.6\n        . org.mozilla/rhino 1.7R5\n        X org.clojure/tools.reader 1.0.0-alpha1 :older-version\n      X org.clojure/tools.reader 1.0.0-alpha3 :older-version\n  . compliment/compliment 0.3.6\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#local-library-install","title":"Local library install","text":"<p>Add a jar file for a library to the local Maven repository, e.g. <code>~/.m2/repository</code>, making that library accessible to all other local projects.</p> <pre><code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'`\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#find-library-versions","title":"Find Library Versions","text":"<p>Find the available versions of a given library in the form domain/library-name (domain is typically the company name or Git Service user or organisation name).</p> <pre><code>clojure -X:deps find-versions :lib clojure.java-time/clojure.java-time\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#prepare-source-dependencies","title":"Prepare Source dependencies","text":"<p>Some dependencies will require a preparation step before they can be used on the classpath.</p> <p>Projects that require preparation would have a configuration of the form:</p> <p>Example</p> <pre><code>{:paths [\"src\" \"target/classes\"]\n :deps/prep-lib {:alias :build\n                 :fn compile\n                 :ensure \"target/classes\"}}\n</code></pre> <p>Including the top-level key <code>:deps/prep-lib</code> tells the tools.deps classpath construction that something extra is needed to prepare this lib and that can be performed by invoking the compile function in the :build alias. Once the prepare step has been done, it should create the path \"target/classes\" and that can be checked for completion.</p> <p>Add a library dependency as with any other library (git or local/root):</p> <p>Example</p> <pre><code>{:deps {practicalli/library-name {:local/root \"../needs-prep\"}\n        practicalli/library-name {:git/sha \"../needs-prep\"}}}\n</code></pre> <p><code>:deps prep</code> will built the library of any dependency that requires it</p> <pre><code>clojure -X:deps prep\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#pom-file","title":"POM file","text":"<p>Generate or update pom.xml with deps and paths</p> <pre><code>clojure -X:deps mvn-pom\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#resolve-git-tags","title":"Resolve Git tags","text":"<p><code>-X:deps git-resolve-tags</code> updates git based dependencies in the project <code>deps.edn</code> file which use :git/tags key to the equivalent SHA commit values in the <code>:git/sha</code> key</p> <pre><code>clojure -X:deps git-resolve-tags\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#references","title":"References","text":"<p>tools.deps and cli guide clojure.main guide clojure.main API Reference tools.deps.alpha API Reference</p>"},{"location":"clojure-cli/clojure-style/","title":"Clojure Style","text":"<p>Code is easier to read and work with when it is consistent format that follows common rules.</p> <p>Clojure community style guide provides a common style for Clojure code.  While most style recommendations are widely used, others are more contentious.  Ultimately the development team for the project should define a workable set of style rules that makes them productions, ideally using much of those rules from the style guide.</p> <p>A consistent format between editors also minimises version control changes not related to code design.  The following format tools for clojure can all be configured to be consistent with each other (although zprint defaults will require more customisation):</p> <ul> <li>cljfmt - library, also included in Clojure LSP</li> <li>cljstyle - binary and library (re-write of cljfmt)</li> <li>zprint - binary &amp; library</li> </ul> Tooling that uses the Clojure Style Guide <p>Emacs <code>clojure-mode</code> and Clojure LSP (via cljfmt) format code following the most common Clojure style guide rules, although cljfmt rules are quite strick so Practicalli disables many of them.</p> <p>cljstyle default configuration follows the majority of styles and has the same defaults as cljfmt.  Practicalli Clojure CLI Config tweaks a few rules to make code more readable and allow for repl design experiments.</p>"},{"location":"clojure-cli/clojure-style/#cljstyle","title":"cljstyle","text":"<p>Cljstyle is a rewrite of cljfmt, designed to be easier to configure. The default rules implement many of the style rules from the Clojure community style guide and is compatible with cljfmt.</p> <p>Call with the <code>check</code> option to report formatting issues, providing a coloured diff view of the format changes</p> <p> </p> <p>Call with <code>fix</code> option to automatically update all Clojure files with fixes, indicating which files have changed.</p> <p>Cljstyle will examine all files in the current directory and any sub-directories.</p> <p><code>.cljstyle</code> configuration file in the root of the project can override the default customisation, including indentation rules.</p> <p>cljstyle config used by Practicalli</p> <p>Clojure App template repository contains the <code>.cljstyle</code> configuration file used for all Practicalli projects</p> Binary Practicalli Clojure CLI ConfigMakefile <p>Install the latest binary release from the cljstyle GitHub repository onto the operating system path, e.g. <code>$HOME/.local/bin</code></p> <pre><code>cljstyle check\n</code></pre> <p><code>fix</code> option automatically updates all source code files that have format issues.</p> <pre><code>cljstyle fix\n</code></pre> <p>cljstyle can be used as a library without installing the cljstyle binary.   Practicalli Clojure CLI Config defines the <code>:format/cljstyle</code> alias which should be passed wither the <code>check</code> or <code>format</code> option</p> <p>Check all the Clojure files (.clj .cljc .edn .cljs) in the current project <pre><code>clojure -M:format/cljstyle\n</code></pre></p> <pre><code>clojure -M:format/cljstyle!\n</code></pre> <p>Clojure Alias for cljstyle</p> <pre><code>:format/cljstyle\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"check\"]}\n\n:format/cljstyle!\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"fix\"]}\n</code></pre> <p>Use a Makefile to run common commands such as checking style, running tests, building uberjars, etc.</p> <p>Practicalli Clojure App template repository contains an example Makefile that contains common tasks for Clojure development</p> <p>This example calls the cljstyle binary, but could be changed to call the <code>clojure -M:format/cljstyle check</code> and <code>clojure -M:format/cljstyle fix</code> aliases instead.</p> <pre><code># ------- Code Quality --------------- #\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n# ------------------------------------ #\n</code></pre> <p>Stage changes before automatically fixing format</p> <p>Practicalli suggests staging (or committing) changes before running <code>cljstyle fix</code> to easily undo undesired changes or simply confirm what changes have been made</p>"},{"location":"clojure-cli/clojure-style/#recommended-configuration","title":"Recommended configuration","text":"<p>Practicalli updated the default cljstyle configuration with the following changes</p> <p>Configure list indent to one character</p> .cljstyle<pre><code>  :indentation\n  {:enabled? true,\n   :list-indent 1,\n\n  }\n</code></pre> <p>Do not warn about duplicate var names (def, defn names) - excluded to stop warning about REPL experiments and design journal rich comments that contain alternative designs.</p> .cljstyle<pre><code>  :vars\n  {:enabled? false}\n</code></pre>"},{"location":"clojure-cli/clojure-style/#cljfmt","title":"cljfmt","text":"<p>cljfmt is not available as a separate binary, although it a fixed part of the Clojure LSP server implementation.</p> <p>whist typing Clojure code, Clojure LSP will format using cljfmt rules</p> <p>Define a cljfmt configuration via Clojure LSP to define rules and indentation settings for all projects.</p> .config/clojure-lsp/config.edn<pre><code> :cljfmt-config-path \"cljfmt.edn\"\n</code></pre> <p>Or specify cljfmt configuration within the Clojure LSP configuration file</p> .config/clojure-lsp/config.edn<pre><code> :cljfmt {}\n</code></pre> Practicalli Clojure LSP config - LSP and cljfmt <p>Practicalli Clojure LSP config provides an example config.edn configuration file for Clojure LSP that uses a cljfmt.edn configuration file for a minimum set of Clojure format rules</p> <p>The default cljfmt rules feel overly strict and Practicalli configuration disables the more draconian rules to make code far more readable</p>"},{"location":"clojure-cli/clojure-style/#zprint","title":"zprint","text":"<p>zprint is a highly configurable format tool for both Clojure code and Clojure/EDN structures, available as a library and command line tool</p> <p>zprint has advanced features over cljstyle and cljfmt, although may require some additional configuration work especially to format consistently with these tools.</p> <p>zprint available styles</p> No built-in diff option <p>zprint requires an external diff tool to see the format changes made, as zprint only reports on the files changed and not the content of those files that has changed.</p> <p>zprint can write changes to a new file and a file comparison made.  Or files can be staged / committed in a local Git repository before running zprint and a Git client used to see the diff.</p> <p>Once the desirable styles and configuration are established there is less need for an external diff tool, although its always useful to have a quick way to check what format tools are doing.</p> Binary Practicalli Clojure CLI ConfigNode.js <p>Download zprint for Linux or MacOSX using the latest binary released on the GitHub repository</p> <p>Move the binary to the executable path for the operating system, updating the name to <code>zprint</code> (or use a symbolic link)</p> <p><pre><code>mv ~/Downloads/zprintl-1.2.5 ~/.local/bin/zprint\n</code></pre> Make the binary executable <pre><code>chmod a+x ~/.local/bin/zprint\n</code></pre> Ensure the zprint binary is working and examine the default configuration for zprint, including all default values and highlighting where non-default values are set <pre><code>zprint --explain-all\n</code></pre> Using zprint to check the Clojure files in the current directory and list which files require formatting <pre><code>zprint --formatted-check *.clj\n</code></pre></p> <p>A more detailed zprint report checking all the Clojure files a project, including files in the route directory and all sub-directories (i.e. <code>**/*.cjl</code> pattern) <pre><code>zprint --list-formatted-summary-check **/*.clj **/*.edn\n</code></pre> Or using short form flags <pre><code>zprint -lfsc **/*.clj **/*.edn\n</code></pre></p> <p>Update formatting for all the files in a projects, showing details of the files processed and changed <pre><code>zprint -lfsw **/*.clj *.edn *.clj\n</code></pre></p> <p>zprint can be used as a library without installing the binary.   Practicalli Clojure CLI Config defines the <code>:format/zprint</code> alias which checks the format of a file and reports which files required</p> <pre><code>clojure -M:format/zprint deps.edn\n</code></pre> <pre><code>clojure -M:format/zprint filename\n</code></pre> Clojure Alias for zprint <p>Add <code>:format/zprint</code> alias to check format and <code>:format/zprint!</code> to write format changes to a given file or filename pattern User or project deps.edn file<pre><code>:format/zprint\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-check\"]}\n\n:format/zprint!\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-write\"]}\n</code></pre> Use the alise</p> <p>zprint is available as an NPM package <pre><code>sudo --install --global zprint-clj\n</code></pre> Run zprint-clj over all Clojure files <pre><code>zprint-clj **/*.{clj,cljs,cljc,edn}\n</code></pre></p>"},{"location":"clojure-cli/clojure-style/#configure-zprint","title":"Configure zprint","text":"<p>It is assumed that the majority of format needs are met by one of the following style rule sets</p> <ul> <li><code>{:style :indent-only}</code> only formats indentation, less likely to change the general style of code</li> <li><code>{:style :community}</code> a quite strict adhearence to the Clojure Community Guide (which Practicalli finds a little to strict)</li> </ul> <p>Unless the code is really messy (e.g. not written in a clojure aware editor with live linting) then <code>{:style :indent-only}</code> is a simple starting point.</p> <p>If the team have adopted most if not all community styles, then <code>{:style :community}</code> may be a more appropriate start point.  Use --explain-all flag with the zprint command to see all the rules that are applied with a partiular style and modify as appropriate</p> <p><code>$HOME/.zprintrc</code> is used for the configuration applied to all files, although this can be overridden in each project (or even as zprint comments in particular files)</p> <p>zprint - GitHub repo zprint - clojars zprint - cljdoc</p>"},{"location":"clojure-cli/defining-aliases/","title":"Defining aliases","text":"<p>Aliases extend the built-in functionality of Clojure CLI via community libraries and tools, either in a project specific or a user <code>deps.edn</code> configuration file.</p> <p>Aliases are explicitly added to the <code>clojure</code> command, e.g. <code>clojure -M:repl/rebel</code> to start a repl with rebel rich terminal UI.</p> <p>Aliases are optional configuration that supports the development workflow.</p> <p>Aliases can be used to :</p> <ul> <li>add libraries and directories to the class path</li> <li>configure how to run community tools and provide default options</li> </ul> Understanding Clojure CLI Execution Options <p>Understand the execution options (exec-opts) on the command line options ensures an effective use of Clojure CLI tools.</p>"},{"location":"clojure-cli/defining-aliases/#configuration-file","title":"Configuration file","text":"<p><code>deps.edn</code> is an EDN configuration file containing a single hash-map with several top-level keywords. All keywords are optional.</p> <ul> <li><code>:paths</code> - directories included by default as a vector of directory names, e.g. <code>[\"src\" \"resources\"]</code></li> <li><code>:deps</code> - library dependencies included by default as a map  (practicalli/banking-on-clojure example)</li> <li><code>:mvn/repos</code> - a map of repositories to download Maven dependencies, Maven Central and Clojars included by default</li> <li><code>:mvn/local-repo</code> to specify an alternative location for the Maven cache</li> <li><code>:aliases</code> - a map of optional libraries and tools, the key being the alias name and its value the configuration</li> </ul> <p>The installation of Clojure CLI contains a configuration</p> <ul> <li>adds <code>src</code> and <code>org.clojure/clojure</code> library</li> <li>Maven Central &amp; Clojars.org repository sources.</li> </ul> <p>Configuration available to all projects (or stand-alone tools) is defined in a user <code>deps.edn</code> configuration in either <code>$XDG_CONFIG_HOME/clojure</code> or <code>$HOME/.clojure</code>.</p> <p>Project specific configuration is defined in a <code>deps.edn</code> file in the root of the Clojure project.</p> User configuration locations <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, then the user configuration is <code>$XDG_CONFIG_HOME/clojure/deps.edn</code></p> <p>Otherwide the user configuration is <code>$HOME/.clojure/deps.edn</code>.</p> <p>The <code>CLJ_CONFIG</code> environment variable will be used if set.</p>"},{"location":"clojure-cli/defining-aliases/#alias-keys","title":"Alias keys","text":"<p>An alias name is a keyword in Clojure, e.g. <code>:test/env</code>, so the <code>:</code> is an intrinsic part of the alias name.</p> <p>Keys used to define an alias are:</p> <ul> <li><code>:extra-paths</code> - a vector of directory names added to the project class path, e.g. <code>[\"env/dev\" \"env/test\"]</code></li> <li><code>:extra-deps</code> - a map of additional library dependencies, as a Maven library, Git repository or local directory</li> <li><code>{domain/library-name {:mvn/version \"1.2.33\"}}</code> maven library</li> <li><code>{domain/name {:git/url \"https://github.com/account-name/repository-name\" :git/sha 'ab3de67'}}</code></li> <li><code>{io.github.account/repository-name {:git/tag \"2023-01-10\" :git/sha 'ab3de67'}}</code></li> <li><code>{}</code></li> <li><code>:main-opts</code> - a vector of command line options passed to <code>clojure.main</code></li> <li><code>:exec-fn</code> - the fully qualified name of a function to be run by <code>clojure.exec</code></li> <li><code>:exec-args</code> - default arguments passed to the function, over-ridden by matching argument keys specified on the command line</li> </ul> <p>Keys used when defining an alias for a standalone tool which exclude the paths and dependencies defined in top-level keys.</p> <ul> <li><code>:replace-paths</code> - use only the paths specified as the class path</li> <li><code>:replace-deps</code> - use only the libraries specified, defined as a Maven library or Git repository</li> </ul> alias :paths and :deps short-cuts <p>Using <code>:paths</code> and <code>:deps</code> keys in an alias are short-cuts for their respective <code>replace-paths</code> and <code>:replace-deps</code> keywords</p> <p>Using <code>:paths</code> and <code>:deps</code> in an alias can be very confusing and Practialli recommends using the explicit names for greater clarity</p> Clojure CLI -T option <p><code>-T</code> execution option will exclude the top-level <code>:paths</code> and <code>:deps</code> keys</p> <p><code>-T</code> sets \".\" as the path, adding only paths and libraries defined in aliases used with the execution flag</p>"},{"location":"clojure-cli/defining-aliases/#clojuremain-alias","title":"clojure.main alias","text":"<p><code>:main-opts</code> specifies the options passed to a clojure.main alias, using the <code>clojure -M</code> execution option flag.</p> <p>The value is a vector containing individual string values that represent each option, i.e. option flag and value.</p> <p><code>-m</code> is used to define the fully qualified namespace in which <code>clojure.main</code> should look for the <code>-main</code> function.</p> <p>The <code>:main-opts</code> vector defines arguments that are passed to the <code>-main</code> function, the same kind of arguments that would be passed via the command line.</p> <p>The <code>\"--middleware\"</code> argument adds cider-nrepl middleware to the nREPL server, allowing Cider and other editors complete control over the REPL.  The syntax uses values wrapped in a vector.</p> <p>The <code>\"-interactive\"</code> argument runs an interactive REPL prompt. A headless process is run without this option.</p> <pre><code>  :repl/cider\n  {:extra-deps {nrepl/nrepl                   {:mvn/version \"0.9.0\"}\n                cider/cider-nrepl             {:mvn/version \"0.27.4\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n                \"-interactive\"]}\n</code></pre> <p>This alias is called using the command <code>clojure -M:repl/cider</code></p>"},{"location":"clojure-cli/defining-aliases/#clojureexec-alias","title":"clojure.exec alias","text":"<p><code>:exec-fn</code> specifies the fully qualified name of the function, using the <code>clojure -X</code> execution option flag .</p> <p><code>:exec-args</code> specifies a hash-map of default key/value pairs passed to the <code>:exec-fn</code> function.  The defaults can be overridden on the command line with respective key/value pairs.</p> <p>Arguments can be nested within the <code>:exec-args</code> map, especially useful on projects with several component configurations (server, database, logging) and managed by a component system (i.e Integrant)</p> <pre><code>{:aliases\n {:project/run\n  {:exec-fn practicalli.service/start\n   :exec-args {:http/server {:port 8080\n                             :join? fale}\n               :log/mulog :elastic-search}}}}\n</code></pre> <p>To run with the default arguments:</p> <pre><code>clojure -X:project/run\n</code></pre> <p>Over-ride the default arguments by passing them on the command line</p> <pre><code>clojure -X:project/run '[:http/server :port]' 8888 :log/mulog :console :profile :dev\n</code></pre> <p>In this command the vector defines the path to the <code>:port</code> key and over-rides the default value. :log/mulog is a top-level key which changes the log publisher type.  <code>:profile</code> is another top-level key that sets the environment to <code>:dev</code> (e.g. to configure Integrant / Aero).</p> <p>Arguments in a nested map within the alias can be traversed (as with <code>get-in</code> and <code>update-in</code> functions) to override the default values in the alias.  So to set a different port value :</p> <p>Argument keys should either be a top-level key or a vector of keys to refer to a key in a nested hash-map of arguments.</p> <p>An alias can contain configuration to run both <code>clojure.main</code> and <code>clojure.exec</code> (useful if steadily migrating users from -M to -X approach without breaking the user experience)</p>"},{"location":"clojure-cli/defining-aliases/#examples","title":"Examples","text":"Practicalli Clojure CLI Config provides a wide range of aliases <p> Practicalli Clojure CLI Config is a configuration designed to work across all Clojure projects, containing unique and meaningful alias names for ease of understanding.</p>"},{"location":"clojure-cli/defining-aliases/#simple-project","title":"Simple Project","text":"<p>A new Clojure project can be made by creating a <code>deps.edn</code> file and respective <code>src</code> &amp; <code>test</code> directory trees.</p> <p>A project <code>deps.edn</code> file typically contains <code>:path</code>, <code>:deps</code> and <code>:aliases</code> sections, although <code>deps.edn</code> could start with a simple <code>{}</code> empty hash-map.</p> <pre><code>{:paths [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}}\n\n :aliases\n {:test/env {:extra-paths [\"test\"]}}}\n</code></pre> <p>The <code>test</code> path and associated libraries are added as an alias as they are not required when packaging or running a Clojure application.  <code>:path</code> and <code>:deps</code> keys are always included by default, <code>:aliases</code> are optional and only included when specified with the <code>clojure</code> command, e.g. <code>clojure -M:test/env</code></p>"},{"location":"clojure-cli/defining-aliases/#clojuremain-tool","title":"clojure.main tool","text":"<p>The Cognitect Lab test runner included the <code>test</code> directory in the class path, so test code will be included when run with this alias.</p> <p>The test runner dependency is pulled from a specific commit shared on GitHub (defined as a Git SHA).</p> <p>The main namespace is set to that library and the <code>-main</code> function is called when using this alias.</p> <pre><code>{:aliases\n\n  :test/cognitect\n  {:extra-paths [\"test\"]\n   :extra-deps  {com.cognitect/test-runner\n                {:git/url \"https://github.com/cognitect-labs/test-runner.git\"\n                 :git/sha     \"f7ef16dc3b8332b0d77bc0274578ad5270fbfedd\"}}\n     :main-opts   [\"-m\" \"cognitect.test-runner\"]}\n}\n</code></pre>"},{"location":"clojure-cli/defining-aliases/#clojure-exec-tool","title":"Clojure Exec tool","text":"<p>With Clojure CLI tools version 1.10.1.697 the <code>-X</code> flag was introduced using aliases with Clojure exec.</p> <p>The configuration should define a fully qualified function that runs the tool.</p> <p>The function should take arguments as key/value pairs as with an Edn hash-map, rather than relying on positional arguments as strings.</p> <p>In this example, <code>:exec-fn</code> defines the fully qualified function name that will be called.  <code>:exec-args</code> is a hash-map of the default key values pairs that are passed to the function as an argument.</p> <pre><code>  :project/new\n  {:replace-deps {seancorfield/clj-new {:mvn/version \"1.1.23\"}}\n   :main-opts    [\"-m\" \"clj-new.create\"]    ;; deprecated\n   :exec-fn      clj-new/create\n   :exec-args    {:template lib :name practicalli/playground}\n   }\n</code></pre> <p>Default arguments can be over-ridden in the command,  e.g. <code>clojure -X:project/new :template app :name practicalli/simple-application</code> uses a different template</p> <p>Additional arguments can be sent when running the command, e.g. <code>clojure -X:project/new :template figwheel-main :name practicalli/landing-page :args '[\"--reagent\"]'</code> uses the <code>figwheel-main</code> template, specifies a name and <code>:args</code> arguments sent to</p> <p><code>:ns-default</code> can also be used to qualify the function that will be executed in an alias.  <code>:ns-default</code> is especially useful when there are several functions that could be called from the specific namespace.</p> <p>The command line can over-ride the <code>:exec-fn</code> function configuration, allowing for a default configuration that can be easily over-ridden.</p> <p>Example</p> <pre><code>  :project/new\n  {:replace-deps {seancorfield/clj-new {:mvn/version \"1.1.226\"}}\n   :main-opts    [\"-m\" \"clj-new.create\"]    ;; deprecated\n   :ns-default   clj-new\n   :exec-fn      create\n   :exec-args    {:template lib :name practicalli/playground}\n   }\n</code></pre> <p>Keyword naming</p> <p>Alias names are a Clojure keyword, which can be qualified to provide context, e.g. <code>:project/create</code>.  </p> <p>Aliases are composable (chained together) and their path and deps configurations merged:</p> <pre><code>clojure -M:task/path:task/deps:build/options\n</code></pre> <p>When multiple aliases contain a <code>:main-opts</code> configurations they are not merged, the configuration in the last alias is used</p>"},{"location":"clojure-cli/defining-aliases/#resources","title":"Resources","text":"<p>clj-exec: insideclojure.org clj-exec update: insideclojure.org Clojure CLI execution options Tips for designing aliases</p>"},{"location":"clojure-cli/design-journal/","title":"Design Journal","text":"<p>A design journal captures with code and comments the decisions taken for a project, invaluable to anyone trying to get up to speed with a project.</p>"},{"location":"clojure-cli/design-journal/#using-a-design-journal-namespace","title":"Using a design-journal namespace","text":"<p>A single namespace encourages the journal to flow as the design of the application flows.  So onboarding onto a project is essentially reading and evaluating code from top to bottom.</p>"},{"location":"clojure-cli/design-journal/#using-comment-blocks","title":"Using comment blocks","text":"<p>It is useful to include examples of how you expect key parts of the system to be called and the kind of arguments they receive.  Placing these examples in a (comment ,,,) expression ensures they are not accidentally evaluated whilst showing the most important function calls in a particular namespace.</p>"},{"location":"clojure-cli/execution-options/","title":"Clojure CLI Execution options","text":"<p>Execution options (<code>-A</code> <code>-M</code> <code>-P</code> <code>-T</code> <code>-X</code>) define how aliases are used with the Clojure CLI. Aliases are included via one of these execution options and each option can affect how the alias is used.</p> Clojure CLI design evolution <p>The first documented released used the <code>-A</code> execution option to include aliases. </p> <p>The design has evolved to provide specific execution options to run code via clojure.main (<code>-M</code>) and clojure.exec (<code>-X</code>). </p> <p>In July 2021 the ability to run tools (<code>-T</code>) independent from the Clojure project classpath was introduced.</p>"},{"location":"clojure-cli/execution-options/#quick-summary","title":"Quick summary","text":"<p><code>-M</code> uses <code>clojure.main</code> to call the <code>-main</code> function of the specified namespace, passing string-based arguments.</p> <p><code>-X</code> uses <code>clojure.exec</code> to call a fully qualified function, passing arguments as key and value pairs</p> <p><code>-T</code> runs a tool independent from project dependencies.  Only the libraries in the alias are included in the Class Path.  The path is defined as <code>\".\"</code> by default.</p> <p><code>-P</code> downloads library dependencies, including those from specified aliases</p> <p><code>-A</code> in the specific case of running a basic terminal UI REPL with the <code>clojure</code> command or <code>clj</code> wrapper.</p>"},{"location":"clojure-cli/execution-options/#clojuremain","title":"clojure.main","text":"<p><code>-M</code> flag instructs Clojure CLI tools to use <code>clojure.main</code> to run Clojure code.</p> <p>The <code>--main</code> or <code>-m</code> flag is an argument to <code>clojure.main</code> which specifies the namespace to search for a <code>-main</code> function.</p> <p><code>clojure.main/main</code> function searches for a <code>-main</code> function in the given namespace, e.g. <code>--main pracicalli.gameboard.service</code></p> <p>If the -main function is not found or the namespace is not specified, then the <code>clojure</code> command will run a REPL session.</p> <p>Run a project with the main namespace <code>practicalli.sudoku-solver</code>, without any additional aliases on the command line</p> <pre><code>clojure -M -m practicalli.sudoku-solver\n</code></pre> <p>Add <code>:project/run</code> alias to the project <code>deps.edn</code> file to provide a simpler way to run the project on the command line</p> <pre><code>:project/run {:main-opts [\"--main\" \"practicalli.sudoku-solver\"]}\n</code></pre> <p>Now the project code can be run using the simple command line form</p> <pre><code>clojure -M:project/run\n</code></pre>"},{"location":"clojure-cli/execution-options/#using-clojuremain","title":"Using clojure.main","text":"<p><code>clojure.main</code> namespace has been the way Clojure code was run (including a REPL) for most of its history.  This is now evolving with the addition of clojure.exec. clojure.main has other features, as covered in the REPL and main entrypoints article) on clojure.org.</p>"},{"location":"clojure-cli/execution-options/#rebel-rich-terminal-ui","title":"Rebel rich terminal UI","text":"<p>Rebel readline provides a terminal UI REPL, providing auto-completion, function signatures, documentation, etc.</p> <p><code>:repl/rebel</code> is an alias that includes nrepl, cider-nrepl and rebel-readline libraries, with a <code>:main-opts</code> to run the <code>rebel-readline.main/-main</code> function via <code>clojure.main</code>.</p> <pre><code>:repl/rebel\n{:extra-deps {nrepl/nrepl                {:mvn/version \"0.9.0\"}\n              cider/cider-nrepl          {:mvn/version \"0.28.2\"}\n              com.bhauman/rebel-readline {:mvn/version \"0.1.4\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n</code></pre> <p>Use the <code>:repl/rebel</code> alias with the <code>-M</code> execution option</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Multiple aliases can be specified to include additional paths and libraries. Aliases chained together have their configuration merged</p> <p><code>:env/dev</code> adds \"dev\" as an extra path, with the <code>dev/user.clj</code> file automatically loading its code into the <code>user</code> namespace when the REPL starts</p> <p><code>:lib/hotload</code> alias adds the <code>org.clojure/tools.deps.alpha</code> library to provide hotloading of dependencies into the running REPL</p> <p>Start a REPL process with this alias</p> <pre><code>clojure -M:env/dev:lib/hotload:repl/rebel\n</code></pre> <p>The Rebel REPL UI will start, include the dev directory on the class path and the <code>org.clojure/tools.deps.alpha</code> library loaded into the REPL</p>"},{"location":"clojure-cli/execution-options/#chaining-aliases","title":"Chaining aliases","text":"<p>Alises can be used together by chaining their names on the command line</p> <pre><code>clojure -M:env/dev:lib/hotload:repl/rebel\n</code></pre> <p>The <code>clojure</code> command will merge the <code>:extra-paths</code> and <code>:extra-deps</code> values from each alias in the chain.</p> <p>The <code>:main-opts</code> values from the aliases are not merged. Only the <code>:main-opts</code> value from the last alias in the chain is used with <code>clojure.main</code> to run the Clojure code.</p> <p>If the command line includes the <code>-m</code> flag with a namespace, then that namespace is passed to <code>clojure.main</code>, ignoring all <code>:main-opts</code> values from the aliases.  The <code>-i</code> and <code>-e</code> flags for clojure.main also replace <code>:main-opts</code> values.</p>"},{"location":"clojure-cli/execution-options/#clojureexec","title":"clojure.exec","text":"<p><code>-X</code> flag provides the flexibility to call any fully qualified function, so Clojure code is no longer tied to <code>-main</code></p> <p>Any function on the class path can be called and is passed a hash-map as an argument.  The argument hash-map is either specified in an alias using <code>:exec-args</code> or assembled into a hash-map from key/value pairs on the command line.  Key/values from the command line are merged into the <code>:exec-args</code> map if it exists, with the command line key/values taking precedence.</p>"},{"location":"clojure-cli/execution-options/#clojureexec-arguments","title":"clojure.exec arguments","text":"<p>Clojure.exec command takes key value pairs read as EDN values (extensible data notation that is the base syntax of Clojure).</p> <p>Number values and keywords can be parsed from the command line</p> <p>Arguments that are vectors and hash maps should be wrapped in single quotes to avoid the command line shell splitting arguments at spaces, e.g. <code>'[:a :b]'</code>, <code>'{:c 1}'</code>.</p> <p>The double quotes in an EDN string must be wrapped by single quotes, along with vectors and hash-maps</p> <ul> <li><code>'\"strings in double quotes surround by single quotes\"'</code></li> <li><code>'[:vectors :with-single-quotes]'</code></li> <li><code>'{:hash-maps :with-single-quotes}'</code></li> </ul>"},{"location":"clojure-cli/execution-options/#clojureexec-examples","title":"clojure.exec examples","text":"<p>Call the <code>status</code> function from the namespace <code>practicalli.service</code>, which is on the classpath in the practicalli.service project</p> <pre><code>clojure -X practicalli.service/status\n</code></pre> <p>Pass arguments to a <code>start</code> function in the <code>practicalli.service</code> namespace</p> <pre><code>clojure -X practicalli.service/start :port 8080 :join? false\n</code></pre> <p>As the arguments are key/value pairs, it does not matter in which order the pairs are used in the command line.</p>"},{"location":"clojure-cli/execution-options/#built-in-functions","title":"Built in functions","text":"<p>Clojure CLI tools has some built in tools under the special <code>:deps</code> alias (not to be confused with the <code>:deps</code> configuration in a <code>deps.edn</code> file)</p> <ul> <li><code>-X:deps mvn-install</code> - install a maven jar to the local repository cache</li> <li><code>-X:deps find-versions</code> - Find available versions of a library</li> <li><code>-X:deps prep</code> - prepare source code libraries in the dependency tree</li> </ul> <p>See <code>clojure --help</code> for an overview or <code>man clojure</code> for detailed descriptions</p>"},{"location":"clojure-cli/execution-options/#run-a-tool","title":"Run a Tool","text":"<p><code>-T</code> install, run and remove a tool, by the tool name or an alias.</p> <p>The <code>-T</code> execution option also uses the <code>clojure.exec</code> approach, although the <code>:deps</code> and <code>:path</code> values from a project <code>deps.edn</code> file are ignored.  This isolates the tool from the dependencies in a Clojure project.</p> <p>Calling Tools on the command line has the general form:</p> <pre><code>clojure -Ttool-name function-name :key \"value\" ,,,\n</code></pre> <p>A tool may provide many functions, so the specific function name is provided when calling the tool.</p> <p>key/value pairs can be passed as arguments to that function (as with the -X execution option)</p> <p><code>-Ttools</code> is a built-in tool to <code>install</code> and <code>remove</code> other tools, with the <code>:as</code> directive providing a specific name for the tool.</p> <p>In this example, the antq tool is installed using the name <code>antq</code></p> <pre><code>clojure -Ttools install com.github.liquidz/antq '{:git/tag \"1.3.1\"}' :as antq\n</code></pre> <p>Installing a tool adds an EDN configuration file using the name of the tool in <code>$XDG_HOME/.clojure/tools/</code> or <code>$HOME/.clojure/tools/</code> directory.</p> <p>Once a tool is installed, run by using the name of the tool.</p> <pre><code>clojure -Tantq outdated\n</code></pre> <p>Options to the tool are passed as key/value pairs (as the tool is called by clojure.exec)</p> <pre><code>clojure -Tantq outdated :upgrade true\n</code></pre> <p><code>-Ttools remove</code> will remove the configuration of the tool of the given name</p> <pre><code>clojure -Ttools remove :tool antq\n</code></pre>"},{"location":"clojure-cli/execution-options/#tools-install-or-aliases","title":"Tools install or aliases","text":"<p>Tools can also be defined in an alias with <code>:exec-fn</code> can be run via <code>-T:alias-name</code> as they are both executed using <code>clojure.exec</code>.</p> <p><code>-X</code> execution option can emulate <code>-T</code> behaviour when an alias uses <code>:replace-paths</code> and <code>:replace-deps</code> keys, instead of <code>:extra-paths</code> and <code>:extra-deps</code>, so project paths and dependencies are not included loaded by the alias.</p> <p>Using an alias for a tool has the advantage allowing a use to define their preferred default arguments that are passed to the <code>:exec-fn</code>, using the <code>:exec-args</code> key.</p> <p>Default arguments could be included in the <code>deps.edn</code> of the installed tool itself, although this is controlled by the developer of that tool project.</p> <p>The <code>:search/outdated</code> alias defined in the <code>practicalli/clojure-deps-edn</code> user level configuration is an example of a tool alias with default arguments</p> <pre><code>  :search/outdated\n  {:replace-paths [\".\"]\n   :replace-deps  {com.github.liquidz/antq {:mvn/version \"1.3.1\"}\n                   org.slf4j/slf4j-nop     {:mvn/version \"1.7.32\"}}\n   :main-opts     [\"-m\" \"antq.core\"]\n   :exec-fn antq.tool/outdated\n   :exec-args {:directory [\".\"] ; default\n               :exclude [\"com.cognitect/rebl\"\n                         \"org.openjfx/javafx-base\"\n                         \"org.openjfx/javafx-controls\"\n                         \"org.openjfx/javafx-fxml\"\n                         \"org.openjfx/javafx-swing\"\n                         \"org.openjfx/javafx-web\"]\n               ;; :focus [\"com.github.liquidz/antq\"]\n               :skip [\"boot\" \"leiningen\"]\n               :reporter \"table\" ; json edn format\n               :verbose false\n               :upgrade false\n               :force   false}}\n</code></pre> <p>This alias is called using <code>clojure -T:search/outdated</code> and is the same as calling <code>clojure -Tantq outdated ,,, ,,,</code> with a long list of key value options that represent the arguments in the alias.</p> <p>As the output is a table of results, the command output is typically pushed to a file: <code>clojure -T:search/outdated &gt; outdated-2021-12-24.txt</code></p> <p>Example tools include</p> <ul> <li>liquidz/antq - search dependencies for newer library versions</li> <li>seancorfield/deps-new - create new projects using templates</li> <li>clojure-nvd - check dependencies against National Vunerability Database</li> </ul>"},{"location":"clojure-cli/execution-options/#prepare-dependencies","title":"Prepare dependencies","text":"<p><code>-P</code> flag instructs the <code>clojure</code> command to download all library dependencies to the local cache and then stop without executing a function call.</p> <p>The <code>-P</code> flag is often used with Continuous Integration workflows and to create pre-populated Container images, to avoid repeatedly downloading the same library jar files.</p> <p>If used with just a project, then the Maven dependencies defined in the project <code>deps.edn</code> file will be downloaded, if not already in the users local cache (<code>~/.m2/repository/</code>).</p> <p>If <code>:git</code> or <code>:local/root</code> dependencies are defined, the respective code will be downloaded and added to the classpath.</p> <p>Prepare flag by itself download dependencies defined in the <code>:deps</code> section of the <code>deps.edn</code> file of the current project.</p> <pre><code>clojure -P\n</code></pre> <p>Including one or more aliases will preparing all the dependencies from every alias specified</p> <pre><code>clojure -P -M:env/dev:lib/hotload:repl/cider\n</code></pre> <p><code>-P</code> flag must be used before any subsequent arguments, i.e. before <code>-M</code>, <code>-X</code>, <code>-T</code></p> <p>As prepare is essentially a dry run, then the <code>clojure</code> command does not call <code>:main-opts</code> or <code>:exec-fn</code> functions, even if they exist in an alias or on the command line.</p> <p><code>-P</code> will warn if a project has dependencies that require building from source (i.e Java code) or resource file manipulation.  If so then <code>clojure -X:deps prep</code> will prepare these source based dependencies.</p>"},{"location":"clojure-cli/execution-options/#built-in-terminal-ui-repl","title":"Built-in terminal UI REPL","text":"<p><code>-A</code> is stated as the official way to include an alias when running a REPL terminal UI <code>clojure</code> or <code>clj</code>.</p> <p>Practicalli recommends using Rebel Readline which uses -M execution option, so -A execution option is rarely used by Practicalli.</p> <p>The <code>:env/dev</code> alias adds \"dev\" directory to the class path, typically used to add a <code>user.clj</code> that will automatically load code from the <code>user</code> namespace defined in that file.</p> <pre><code>clojure -A:env/dev\n</code></pre> <p>The alias definition is <code>:env/dev {:extra-paths [\"dev\"]}</code></p> <p>Aliases can be chained together and their configuration will be merged</p> <p><code>:lib/hotload</code> adds a dependency to provide hotloading of other dependencies</p> <pre><code>:lib/hotload\n{:extra-deps {org.clojure/tools.deps.alpha\n                {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                 :sha     \"d77476f3d5f624249462e275ae62d26da89f320b\"}\n              org.slf4j/slf4j-nop {:mvn/version \"1.7.32\"}}}\n</code></pre> <p>Start a REPL process with this alias</p> <pre><code>clojure -A:env/dev:lib/hotload\n</code></pre> <p>Use -M for alias definitions including :main-opts</p> <p>Using an alias that contains a <code>:main-opts</code> key with <code>-A</code> will fail to run a REPL and print a warning to use <code>-M</code> execution option The <code>:main-opts</code> configuration for <code>-A</code> execution option is deprecated (although currently works in 1.10.x). To run Clojure code via <code>clojure.main</code> the <code>-M</code> option should be with aliases that includes <code>:main-opts</code>.</p>"},{"location":"clojure-cli/execution-options/#summary","title":"Summary","text":"<p>There are many options when it comes to running Clojure CLI tools that are not covered here, however, this guide gives you the most common options used so far.</p> <p>Practicalli recommends using the <code>-X</code> execution option where possible, as arguments follow the data approach of Clojure design.</p> <p>The <code>-J</code> and <code>:jvm-opts</code> are useful to configure the Java Virtual machine and deserve an article to themselves as there are many possible options.</p> <p>The <code>-T</code> tools is an exciting and evolving approach and it will be interesting to see how the Clojure community adopt this model.</p> <p>See the Deps and CLI Reference Rationale for more details and description of these options.</p>"},{"location":"clojure-cli/execution-options/#references","title":"References","text":"<ul> <li>Inside Clojure - clj exec</li> <li>Inside Clojure - clj exec update</li> </ul>"},{"location":"clojure-cli/practicalli-config/","title":"Practicalli Clojure CLI Configuration","text":"<p> Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI Config is a user configuration for Clojure CLI tools providing a range of community tools via meaningful aliases, supporting Clojure and ClojureScript development.</p> <p>Alias names are designed with qualified keywords that provide context for the use of an alias (<code>env</code>, <code>inspect</code>, <code>project</code>, <code>repl</code>, <code>search</code> <code>test</code>). These keywords help with discovery and reduce cognitive load required to remember their purpose.</p> <p>Commonly used arguments are included in many alias via <code>:main-opts</code> or <code>:exec-args</code> which can be overridden on the command line.</p> Minimum Clojure CLI Version - 1.10.3.1040 <p>Clojure CLI version 1.10.3.1040 is the minimum version, although the latest available version is recommended.</p> <p>Check the version of Clojure CLI currently installed via <code>clojure --version</code> or <code>clojure -Sdescribe</code></p> Remote Environments or Continuous Integration <p>For remote environments or Continuous Integration services, include  Practicalli Clojure CLI Config) in the environment build or copy specific aliases to the Clojure project <code>deps.edn</code> configuration.</p>"},{"location":"clojure-cli/practicalli-config/#install","title":"Install","text":"<p>Fork or clone  Practicalli Clojure CLI Config GitHub repository, first removing the <code>$XDG_CONFIG_HOME/clojure</code> or <code>$HOME/.clojure</code> directory if they exist.</p> Check Clojure CLI configuration location <p>Check the location of your Clojure configuration directory by running <code>clojure -Sdescribe</code> and checking the <code>:user-config</code> value.</p> Free Desktop XDG CONFIGClassic Config <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, clone the repository to <code>$XDG_CONFIG_HOME/clojure</code></p> <pre><code>git clone https://github.com/practicalli/clojure-deps-edn.git $XDG_CONFIG_HOME/clojure\n</code></pre> <p>Clojure CLI will look for its configuration in <code>$HOME/.clojure</code> directory if <code>$XDG_CONFIG_HOME</code> and <code>CLJ_CONFIG</code> environment variables not set.</p> <pre><code>git clone https://github.com/practicalli/clojure-deps-edn.git $HOME/.clojure\n</code></pre>"},{"location":"clojure-cli/practicalli-config/#community-tools","title":"Community Tools","text":"<p>The Clojure configuration directory contains a <code>deps.edn</code> file containing a substantial <code>:aliases</code> section with a long list of aliases.  These aliases are described in the  README of the project.</p> <p>All tools are provided via libraries and are only installed on first use.  Unused aliases will therefore not install their libraries.</p> <p>Aliases to start with</p> <p>Start with the following aliases to keep things simple</p> <p><code>clojure -T:project/create :name domain/project-name</code> to create a new clojure project</p> <p><code>clojure -M:repl/reloaded</code> to run a fully loaded REPL and rich terminal UI (which can be connected to from Clojure editors)</p> <p><code>clojure -X:test/watch</code> to run tests on file save (or <code>:test/run</code> to manually run tests once)</p> <p>Use Clojure tools.build to create jar and uberjar packages of the project.</p>"},{"location":"clojure-cli/practicalli-config/#repl-experience","title":"REPL experience","text":"<p>Rebel REPL terminal UI provides a feature rich REPL prompt experience, far beyond the basic <code>clj</code> command.</p> Command Description <code>clojure -M:repl/rebel</code> Rebel terminal UI <code>clojure -M:env/dev:repl/rebel</code> Rebel including deps &amp; path from <code>:env/dev</code> alias to configure REPL start <code>clojure -M:repl/reloaded</code> Rebel with <code>dev</code> &amp; <code>test</code> paths, library hotload, namespace reload, portal data inspector <code>clojure -M:repl/rebel-cljs</code> Run a ClojureScript REPL using Rebel Readline <p><code>:repl/help</code> in the REPL for help and available commands.  <code>:repl/quit</code> to close the REPL.</p>"},{"location":"clojure-cli/practicalli-config/#clojure-projects","title":"Clojure Projects","text":"<ul> <li>Create Clojure CLI specific projects using deps-new</li> <li>Create projects from deps, leiningen and boot templates with clj-new</li> </ul> Command Description <code>clojure -T:project/create</code> library project called playground <code>clojure -T:project/create :template app :name practialli/service</code> Clojure CLI project from app template <code>clojure -T:project/new :template luminus :name practicalli/full-stack-app +http-kit +h2</code> Luminus project with given name and template options"},{"location":"clojure-cli/practicalli-config/#run-projects","title":"Run projects","text":"<p>Run project with or without an alias:</p> <pre><code>clojure -M:alias -m domain.app-name\nclojure -M -m domain.app-name\n</code></pre> <p>The <code>-M</code> flag is required even if an alias is not included in the running of the application.  A warning will be displayed if the <code>-M</code> option is missing.</p> <p>In the project deps.edn file it could be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.</p> <pre><code>:project/run\n{:ns-default domain.main-namespace\n :exec-fn -main\n :exec-args {:port 8888}}\n</code></pre> <p>Then the project can be run using <code>clojure -X:project/run</code> and arguments can optionally be included in this command line, to complement or replace any default arguments in <code>exec-args</code>.</p>"},{"location":"clojure-cli/practicalli-config/#project-dependencies","title":"Project dependencies","text":"Command Description <code>clojure -M:project/errors</code> detailed report of compilation errors for a project <code>clojure -M:search/libraries library-name</code> fuzzy search Maven &amp; Clojars <code>clojure -M:search/libraries -F:merge library-name</code> fuzzy search Maven &amp; Clojars and save to project deps.edn <code>clojure -M:search/outdated</code> report newer versions for maven and git dependencies <code>clojure -M:search/unused-vars</code> search and remove unused vars"},{"location":"clojure-cli/practicalli-config/#project-deployment","title":"Project Deployment","text":"<p>Deploy a project archive file locally or to Clojars.org</p> <p>Package projects into jars using tools.build</p> <p>Clojure tools.build is the recommended way to create library jar files and application Uberjar files.</p> Command Description <code>clojure -X:deps mvn-install project.jar</code> [NEW] deploy jar file to local maven repository, i.e. <code>~/.m2/repository</code> <code>clojure -M:project/clojars project.jar</code> deploy jar file to Clojars <code>clojure -M:project/clojars-signed project.jar</code> deploy signed jar file to Clojars <p>Set Clojars username/token in <code>CLOJARS_USERNAME</code> and <code>CLOJARS_PASSWORD</code> environment variables.</p> <p>Set fully qualified artifact-name and version in project <code>pom.xml</code> file</p> <p>Path to project.jar can also be set in alias to simplify the Clojure command.</p> <p><code>clojure -X:deps mvn-install project.jar</code> for local deployment of jars is part of the 1.10.1.697 release of the Clojure CLI tools in September 2020.</p>"},{"location":"clojure-cli/practicalli-config/#java-sources","title":"Java Sources","text":"<p>Include Java source on the  classpath to look up Java Class and method definitions, e.g. <code>cider-find-var</code> in Emacs Requires: Java sources installed locally (e.g. \"/usr/lib/jvm/openjdk-11/lib/src.zip\")</p> <ul> <li><code>:lib/java17-source</code></li> </ul> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p>"},{"location":"clojure-cli/practicalli-config/#format-tools","title":"Format tools","text":"<p>Use formatting tools to support a consistent code style across all Clojure projects</p> Command Description <code>clojure -M:format/cljstyle check / fix</code> Check or fix code style (cljstyle) <code>clojure -M:format/cljfmt check / fix</code> Check or fix code style (cljfmt) <code>clojure -M:format/zprint filename</code> Format file using zprint <p>Include <code>:lib/pprint-sorted</code> when starting a REPL to pretty print data with sorted keys and set values</p>"},{"location":"clojure-cli/practicalli-config/#databases-and-drivers","title":"Databases and drivers","text":"<p>Databases and drivers, typically for development time inclusion such as embedded databases</p> <ul> <li><code>:database/h2</code> - H2 embedded database library and next.jdbc</li> <li><code>lib/next.jdbc</code> - include the next.jdbc library</li> </ul> <p><code>clojure -M:database/h2</code> - run a REPL with an embedded H2 database and next.jdbc libraries</p> <p>https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/doc/getting-started#create--populate-a-database</p> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p>"},{"location":"clojure-cli/practicalli-config/#data-science","title":"Data Science","text":"<ul> <li><code>lib/clerk</code> - Clerk Notebooks</li> </ul>"},{"location":"clojure-cli/practicalli-config/#visualizing-projects","title":"Visualizing projects","text":"<p>Create Graphviz graphs of project and library dependencies</p> <p>Morpheus creates grahps of project vars and their relationships</p> <ul> <li><code>:graph/vars</code> - generate graph of vars in a project as a .dot file</li> <li><code>:graph/vars-png</code> - generate graph of vars in a project as a .png file using <code>src</code> and <code>test</code> paths</li> <li><code>:graph/vars-svg</code> - generate graph of vars in a project as a .svg file using <code>src</code> and <code>test</code> paths</li> </ul> <p>Install Graphviz to generate PNG and SVG images.  Or use the Edotor website to convert .dot files to PNG or SVG images and select different graph layout engines.</p> <p>Vizns creates graphs of relationships between library dependencies and project namespaces</p> <ul> <li><code>:graph/deps</code></li> <li><code>:graph/deps-png</code> - generate a single deps-graph png image</li> </ul> <p>Other options: - <code>clojure -M:graph/deps navigate</code>  # navigable folder of SVGs - <code>clojure -M:graph/deps single</code>    # deps-graph.dot file - <code>clojure -M:graph/deps single -o deps-graph.png -f png</code> - <code>clojure -M:graph/deps single -o deps-graph.svg -f svg</code> - <code>clojure -M:graph/deps single --show</code>  # View graph without saving</p>"},{"location":"clojure-cli/practicalli-config/#data-inspector","title":"Data Inspector","text":"<p>Portal Navigate data in the form of edn, json and transit</p> <p>Practicalli Clojure - data browsers section - portal</p> Command Description <code>clojure -M:inspect/portal-cli</code> Clojure REPL with Portal dependency <code>clojure -M:inspect/portal-web</code> ClojureScript web browser REPL with Portal dependency <code>clojure -M:inspect/portal-node</code> ClojureScript node.js REPL with Portal dependency <p>Using Portal once running</p> <p><code>(require '[portal.api :as portal])</code> once the REPL starts.  For <code>inspect/portal-web</code> use <code>(require '[portal.web :as portal])</code> instead</p> <p><code>(portal/open)</code> to open the web based inspector window in a browser.</p> <p><code>(portal/tap)</code>to add portal as a tap target (add-tap)</p> <p><code>(tap&gt; {:accounts [{:name \"jen\" :email \"jen@jen.com\"} {:name \"sara\" :email \"sara@sara.com\"}]})</code> to send data to the portal inspector window (or any other data you wish to send)</p> <p><code>(portal/clear)</code> to clear all values from the portal inspector window.</p> <p><code>(portal/close)</code> to close the inspector window.</p>"},{"location":"clojure-cli/practicalli-config/#clojure-specification","title":"Clojure Specification","text":"<p>Clojure spec, generators and test.check</p> <ul> <li><code>:lib/spec-test</code> - generative testing with Clojure test.check</li> <li><code>:lib/spec2</code> - experiment with the next version of Clojure spec - alpha: design may change</li> </ul>"},{"location":"clojure-cli/practicalli-config/#unit-testing-frameworks","title":"Unit Testing frameworks","text":"<p>Unit test libraries and configuration.  The Clojure standard library includes the <code>clojure.test</code> namespace, so no alias is required.</p> <ul> <li><code>:test/env</code> - add <code>test</code> directory to classpath</li> <li><code>:lib/expectations</code> - <code>clojure.test</code> with expectations</li> <li><code>:lib/expectations-classic</code> - expectations framework</li> </ul> <p>Use expectations in a project <code>clojure -M:test:expectations</code> or from the command line with a test runner, e.g. <code>clojure -M:lib/expectations:test/runner</code></p>"},{"location":"clojure-cli/practicalli-config/#test-runners-and-test-coverage","title":"Test runners and Test Coverage","text":"<p>Tools to run unit tests in a project which are defined under <code>test</code> path.</p> <p>Run clojure with the specific test runner alias: <code>clojure -M:test-runner-alias</code></p> Command Description <code>clojure -M:test/run</code> Kaocha test runner for Clojure <code>clojure -M:test/watch</code> Kaocha: watch for changes <code>clojure -M:test/cljs</code> Kaocha test runner for ClojureScript"},{"location":"clojure-cli/practicalli-config/#lint-tools","title":"Lint tools","text":"<p>Static analysis tools to help maintain code quality and suggest Clojure idioms.</p> Command Description <code>clojure -M:lint/clj-kondo</code> comprehensive and fast static analysis lint tool <code>clojure -M:lint/eastwood</code> classic lint tool for Clojure <code>clojure -M:lint/idiom</code> Suggest idiomatic Clojure code"},{"location":"clojure-cli/practicalli-config/#performance-testing","title":"Performance testing","text":"<p><code>:performance/benchmark</code> alias includes the Criterium library for performance testing of Clojure expressions.</p> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p> <p><code>:dev/reloaded</code> and <code>:repl/reloaded</code> both include criterium library</p> <p>Start a REPL using the <code>:repl/reloaded</code> alias, or by including the <code>:performance/benchmark</code> in a Clojure command to start a REPL.</p> Repl Reloaded <p>```shell clojure -M:repl/reloaded</p> <p>```</p> Clojure command <p>```shell clojure -M:performance/benchmark:repl/basic</p> <p>```</p> REPL <p>Require the Criterium <code>quick-bench</code> function</p> <pre><code>(require '[criterium.core :refer [quick-bench]])\n</code></pre> <pre><code>(quick-bench (adhoc-expression))\n</code></pre> <p>Performance test a project in the REPL</p> <pre><code>clojure -M:performance/benchmark:repl/rebel\n\n(require '[practicalli/namespace-name]) ; require project code\n(in-ns 'practicalli/namespace-name)\n(quick-bench (project-function args))\n</code></pre> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p> <p>In the REPL:</p> <pre><code>  (require '[clj-memory-meter.core :as memory-meter])\n   (memory-meter/measure (your-expression))\n</code></pre>"},{"location":"clojure-cli/repl-reloaded/","title":"Practicalli REPL Reloaded Workflow","text":"<p>An effective REPL workflow is central to Clojure development. Practicalli REPL Reloaded workflow provides a rich set of tools and minimises the need to restart the REPL</p> <ul> <li>custom REPL startup using <code>dev/user.clj</code></li> <li>continually run unit tests with Kaocha</li> <li>event log and publisher with mulog</li> <li> visualise &amp; navigate evaluation data and logs with Portal</li> <li>hotload libraries without restarting the REPL with <code>clojure.repl.deps</code> (Clojure 1.12)</li> <li>reload changed namespaces to manage large code refactor with <code>tools.namespace</code></li> <li>performance testing code expressions with time &amp; Criterium</li> </ul> <p></p>"},{"location":"clojure-cli/repl-reloaded/#start-the-repl","title":"Start the REPL","text":"<p>Start a Clojure REPL with the <code>:repl/reloaded</code> alias (or include <code>:dev/reloaded</code> alias in an Editor jack-in command or other REPL startup command).</p> <p>Aliases are defined in  Practicalli Clojure CLI Config</p> <p>Start a rich terminal UI repl and the REPL Reloaded tools</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>A  Rebel rich terminal UI REPL prompt provides direct evaluation in the REPL (with autocomplete, documentation, signature hints and multi-line editing)</p> <p>An nREPL server is started to allow connections from a range of Clojure editors.</p> <p>Portal Inspector window opens and is connected to all evaluation results and Mulog events that occur.</p> <p> Rebel REPL Teminal UI</p> Example Alias Definitions <p>Start a REPL process with an nREPL server to connect Clojure editors. Providing a Rebel rich terminal UI with tools to hotload libraries, reload namespaces and run Portal data inspector.  The alias also includes a path for custom REPL startup and a path to access unit test code, along with a test runner. <pre><code>:repl/reloaded\n{:extra-paths [\"dev\" \"test\"]\n :extra-deps {nrepl/nrepl                  {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl            {:mvn/version \"0.30.0\"}\n              com.bhauman/rebel-readline   {:mvn/version \"0.1.4\"}\n              djblue/portal                {:mvn/version \"0.35.1\"}\n              org.clojure/tools.namespace  {:mvn/version \"1.4.1\"}\n              org.slf4j/slf4j-nop          {:mvn/version \"2.0.6\"}\n              com.brunobonacci/mulog       {:mvn/version \"0.9.0\"}\n              lambdaisland/kaocha          {:mvn/version \"1.77.1236\"}\n              org.clojure/test.check       {:mvn/version \"1.1.1\"}\n              ring/ring-mock               {:mvn/version \"0.4.0\"}\n              criterium/criterium          {:mvn/version \"0.4.6\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n\n:dev/reloaded\n{:extra-paths [\"dev\" \"test\"]\n :extra-deps  {djblue/portal                {:mvn/version \"0.35.1\"}\n               org.clojure/tools.namespace  {:mvn/version \"1.4.1\"}\n               org.slf4j/slf4j-nop          {:mvn/version \"2.0.6\"}\n               com.brunobonacci/mulog       {:mvn/version \"0.9.0\"}\n               lambdaisland/kaocha          {:mvn/version \"1.77.1236\"}\n               org.clojure/test.check       {:mvn/version \"1.1.1\"}\n               ring/ring-mock               {:mvn/version \"0.4.0\"}\n               criterium/criterium          {:mvn/version \"0.4.6\"}}}\n</code></pre></p> <p>Include the <code>:dev/reloaded</code> or <code>:lib/hotload</code> aliases when starting the REPL with other aliases, using any of the available Clojure CLI execution options (<code>-A</code>,<code>-M</code>,<code>-X</code>,<code>-T</code>).</p> <p>Alias example from  Practicalli Clojure CLI Config</p> Clojure 1.11 Hotload Support <p>To support Clojure 1.11.x, add an <code>:lib/hotload</code> alias for the <code>clojure.tools.deps.alpha.repl</code> library using the latest SHA commit from the  add-libs3 branch of <code>clojure.tools.deps.alpha</code> library as an extra dependency.</p> <p>The <code>add-libs</code> code is on a separate , so requires the SHA from the head of add-libs3 branch</p> <p><pre><code>  :lib/hotload\n  {:extra-deps {org.clojure/tools.deps.alpha\n               {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> Include the <code>:dev/reloaded</code> or <code>:lib/hotload</code> aliases when starting the REPL with other aliases, using any of the available Clojure CLI execution options (<code>-A</code>,<code>-M</code>,<code>-X</code>,<code>-T</code>).</p> <p>Alias example from  Practicalli Clojure CLI Config</p>"},{"location":"clojure-cli/repl-reloaded/#custom-repl-startup","title":"Custom REPL startup","text":"<p>A Clojure REPL starts in the <code>user</code> namespace. When a <code>user.clj</code> file is on the classpath its code is loaded (evaluated) into the REPL during startup.</p> <p>Create a <code>dev/user.clj</code> file with libraries and tools to support development and add the <code>dev</code> directory to the classpath.</p> <p>Create a custom REPL Startup with dev/user.clj</p>"},{"location":"clojure-cli/repl-reloaded/#reload-namespaces","title":"Reload namespaces","text":"<p>As code and design evolves, expressions evaluated in the REPL may become stale especially when the names (symbols, vars) bound to function definitions are renamed or deleted from the source code.  Rather than restart the REPL process and loose all the state, one or more namespaces can be refreshed.</p> Remove function definitions before renaming <p>To minimise the need to reload namespaces, undefine function definitions (unbind their name to the function) before changing the names of the function.</p> <p>Remove a symbol from the namespace, using <code>*ns*</code> which is dynamically bound to the current namespace <pre><code>(ns-unmap *ns* 'function-or-def-name)\n</code></pre> Remove a specific namespace (any functions defined in the namespace are no longer accessible - illegalStateException - Attempting to call unbound function) <pre><code>(remove-ns 'practicalli.service.utils)\n</code></pre> Remove an alias for a specific namespace <pre><code>(ns-unalias 'practicalli.service.utils 'utils)\n</code></pre></p> <p>Clojure editors may provide commands to undefine a function definition, e.g. Emacs CIDER includes <code>cider-undef</code> to remove the current symbol via nREPL commands</p> <p>clojure.tools.namespace.repl contains the <code>refresh</code> function that compares source code files with the definitions in the REPL, removing and re-evaluating those namespaces containing changes.</p> <p>refresh will manage loading of namespaces with respect to their dependencies, ensuring each namespace can be loaded without error.</p> <p>Require the clojure.tools.namespace.repl refresh function</p> REPLProject <pre><code>(require '[clojure.tools.namespace.repl :refer [refresh]])\n</code></pre> <p>Use an ns form for the namespace (often added to a custom <code>user</code> namespace)</p> <pre><code>(ns user\n  (:require [clojure.tools.namespace.repl :refer [refresh]]))\n</code></pre> <p>Or in a rich comment expression</p> <pre><code>(comment\n  (require '[clojure.tools.namespace.repl :refer [refresh]]))\n</code></pre> <p>Refresh the namespaces that have saved changes</p> <pre><code>(refresh)\n</code></pre> <p>A list of refreshed namespaces are printed.  If there are errors in the Clojure code, then a namespace cannot be loaded and error messages are printed. Check the individual code expressions in the namespace to ensure they are correctly formed.</p> <p>Reload namespaces with dev/user.clj</p> Handling Errors <p>If an exception is thrown while loading a namespace, refresh stops and prints the namespace that caused the exception. (clojure.repl/pst) prints the rest of the stack trace</p> <p><code>*e</code> is bound to the exeception so will print the exeception when evaluated</p> tools.namespace refactor - documentation can be misleading <p><code>refresh</code> and other functions were moved to the <code>clojure.tools.namespace.repl</code> namespace. The original <code>clojure.tools.namespace</code> functions are deprecated, although the new <code>clojure.tools.namespace.repl</code> namespace is not deprecated.</p> <p>Clojure tools.namespace API reference Namespaces Reference - Clojure.org</p>"},{"location":"clojure-cli/repl-reloaded/#hotload-libraries","title":"Hotload Libraries","text":"<p><code>clojure.repl.deps</code> provides functions to hotload libraries into a running REPL, avoiding the need to restart the REPL and loose state just to use a new library with the project.</p> <ul> <li><code>add-lib</code> finds a library by name and adds it to the REPL</li> <li><code>add-libs</code> takes a hash-map of one or more library name and version key/value pairs and adds them to the REPL</li> <li><code>sync-deps</code> reads the project <code>deps.edn</code> file and adds <code>:deps</code> dependencies to the REPL that are not already loaded</li> </ul> <p>Hotload functions are typically called from a rich comment block in a separate <code>dev/user.clj</code> file to avoid being automatically loaded.</p> <p>Once hot-loaded, a library namespace can be required as if the dependency had been added to the project configuration before the REPL started.</p> <p>practicalli/clojure-webapp-hotload-libraries is an example project that uses REPL driven development and hot loading of libraries to build a very simple web server using http-kit and hiccup.</p> Hotload requires Clojure 1.12 &amp; latest Clojure CLI <p>Install the latest Clojure CLI version and use Clojure 1.12 onward to use the officially released hotload library.</p> <p><code>add-libs</code> is an unofficial feature for Clojure 1.11.x and available only in the add-libs3 branch of the now deprecated <code>clojure.tools.deps.alpha</code> library.</p> Hotload simple web server and build a page <pre><code>(comment\n  ;; Require if not automatically loaded by the REPL tooling, ie. Rebel Readline\n  #_(require '[clojure..deps.repl :refer [add-lib add-libs sync-deps]])\n\n  ;; hotload the libraries required for the server\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n\n  (require '[org.httpkit.server :as app-server])\n\n  ;; Discover which http-kit functions are available\n  (ns-publics (find-ns 'org.httpkit.server))\n\n  ;; Define an entry point for the application\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ) ; End of rich comment block\n</code></pre> <p>There are several approaches to hotload libraries, including via a terminal REPL UI or in a project with a Clojure editor:</p> <ul> <li>Rich terminal UI REPL</li> <li>Hotload in a Project</li> </ul>"},{"location":"clojure-cli/repl-reloaded/#unit-test-runner","title":"Unit test runner","text":"<p>Unit tests are written with <code>clojure.test</code> and reside in a parallel <code>test</code> directory, creating matching <code>_test.clj</code> files for each relevant clojure file under <code>src</code>.</p> <p>Test runners are highly configurable and can run a very specific set of tests, although Clojure is usually fast enough to run all the tests each time.</p> <p>Run the tests in a project with the kaocha test runner by issuing the following command in the root of the project.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Or continually watch for changes and run kaocha test runner each time a file is saved (typically in a separate terminal)</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Test run will stop on the first failed test unless <code>:fail-fast? false</code> is passed as an argument to either command.</p> Running Unit Tests in an Editor <p>Emacs and Neovim can run the kaocha test runner if one of the <code>:repl/reloaded</code>, <code>:dev/reloaded</code> or <code>:lib/kaocha</code> aliases are used to start the Clojure REPL.</p> <p>Emacs, Neovim and VS Code Calva also have their own built-in test runners. Test and source code must be evaluated in the REPL for the editor test runners to discover this code.  Editor test runners to not read code from the Clojure files in <code>src</code> or <code>test</code> directories.</p> <p>Writing Unit Tests for Clojure Using Test Runners with Projects</p>"},{"location":"clojure-cli/repl-reloaded/#performance-tests","title":"Performance tests","text":"<p><code>time</code> is a quick way to see if an expression is worth further performance investigation.</p> <p><code>(time ,,,)</code> wrapped around an expression will print the duration that expression took to run.  This provides a very rough indicator of the performance of code, although as it only runs once then results may vary and are easily affected by the environment (Java Virtual Machine, Operating System, other concurrent processes).</p> <p>Criterium provides more realistic performance results which are less affected by the environment, providing a better indication of performance to inform design choices.</p> <p>Criterium tools take a little longer to run in order to return more accurate and consistent performance results.</p> REPLProject <p>Require the criterium library <pre><code>(require '[criterium.core :as benchmark])\n</code></pre></p> <p>Require the criterium library via the ns expression</p> <p><pre><code>(ns user\n  (:require [criterium.core :as benchmark]))\n</code></pre> Or require the criterium library in a rich comment expression <pre><code>(comment\n  (require '[criterium.core :as benchmark]))\n</code></pre></p> <p>Wrap the <code>quick-bench</code> function around the expression to run performance testing upon</p> <pre><code>(benchmark/quick-bench ,,,)\n</code></pre> <p>The expression being tested will be called multiple times and the duration and average times will be printed.</p> <p>Criterium automatically adjusts the benchmark run time according to the execution time of the measured expression. If the expression is fast, Criterium will run it plenty of times, but if a single iteration is quite slow, it will be executed fewer times</p> <p>Use quick-bench rather than bench</p> <p>The bench macro is claimed to be more accurate than quick-bench, but in practice, it runs for much longer and doesn't yield significantly different results in most cases</p> <p>Criterium API Documentation Benchmark with Criterium article</p>"},{"location":"clojure-cli/repl-reloaded/#log-and-publish-events","title":"Log and publish events","text":"<p>mulog is a micro-logging library that logs events and data extremely fast and provides a range of publishers for log analysis.</p> <p>Use the mulog <code>log</code> function to create events to capture useful information about the Clojure system operation.  Publish the logs locally to a console or to a log analysis service such as zipkin or Grafana</p> REPLProject <p>Require the mulog library <pre><code>(require '[com.brunobonacci.mulog :as mulog])\n</code></pre></p> <p>Require the mulog library via the namespace form <pre><code>(ns your-ns\n  (:require [com.brunobonacci.mulog :as mulog]))\n</code></pre></p> <p>Optionally create an event global context, containing information that will be included in every event created</p> <pre><code>(mulog/set-global-context! {:service-name \"Practicalli GameBoard\", :version \"1.0.1\", :env \"dev\"})\n</code></pre> <p>Create events with an identity that contains key/value pairs of data that captures the desired information about the event.</p> <pre><code>(mulog/log ::system-started :version \"0.1.0\" :init-time 32)\n</code></pre> <p>Start a publisher to see all the events created.  The publisher can be to the console or to log analysis tools like zipkin or Grafana</p> <pre><code>(mulog/start-publisher! {:type :console})\n</code></pre> <p><code>trace</code> provides accurate data around instrumented operations of a single system or over a distributed system. trace data can be used in Elasticsearch and real-time streaming system sudh as Apache Kafka.</p> <p>trace will track the rate of a complex operation, including the outcome and latency, within the contextual information of that operation.</p> <p>Consider a function that calls several external services</p> <pre><code>(defn product-status [product-id]\n  (let [stock (http/get availability-service {:product-id product-id})\n        pricing (http/get pricing-service {:product-id product-id})]))\n</code></pre> <p>Create a trace between the function calls</p> <pre><code>(mulog/trace ::product-status\n  [:product-id product-id]\n  (product-status product-id))\n</code></pre> <p><code>trace</code> starts a timer then calls <code>(product-status product-id)</code>. Once the execution completes a log an event is created using <code>log</code> and uses the global context. By including the product id in the trace call, information is captured about the specific product involved in the trace log.</p> <pre><code>;; {:mulog/event-name :practicalli.service/products,\n;;  :mulog/timestamp 1587504242983,\n;;  :mulog/trace-id #mulog/flake \"4VTF9QBbnef57vxVy-b4uKzh7dG7r7y4\",\n;;  :mulog/root-trace #mulog/flake \"4VTF9QBbnef57vxVy-b4uKzh7dG7r7y4\",\n;;  :mulog/duration 254402837,\n;;  :mulog/namespace \"practicalli.service\",\n;;  :mulog/outcome :ok,\n;;  :app-name \"Practicalli GameBoard\",\n;;  :env \"dev\",\n;;  :version \"1.0.1\"}\n</code></pre>"},{"location":"clojure-cli/repl-reloaded/#trace-function-calls","title":"Trace function calls","text":"<p>clojure.tools.trace can trace values, functions and a whole namespace of functions.</p> <p>Tracing a value will show how that value flows through the code</p> <p>Tracing a function shows the arguments passed to the function each time it is called and the results.  Tracing will identify forms that are failing and also show the results of the function call, helping spotting unwanted <code>nil</code> arguments and parts of a function definition that is failing.</p> <ul> <li><code>trace</code> values, optionally assigning a tag</li> <li><code>trace-vars</code> dynamically trace a given fully qualified function</li> <li><code>untrace-vars</code> - remove trace from a given fully qualified function</li> <li><code>trace-ns</code> dynamically trace all functions in the given namespace</li> <li><code>untrace-ns</code> remove trace from all functions in the given namespace</li> </ul> <p><code>:repl/reloaded</code> and <code>:dev/reloaded</code> include the clojure.tools.trace dependency, i.e. <code>org.clojure/tools.trace {:mvn/version \"0.7.11\"}</code></p> <p>tools.trace API Reference</p> REPLProject <p>Require the <code>clojure.tools.trace</code> library and refer the <code>trace</code> and <code>untrace</code> functions <pre><code>(require '[clojure.tools.trace :as trace])\n</code></pre></p> <p>Require the <code>clojure.tools.trace</code> library using the alias <code>trace</code></p> <pre><code>(ns user\n  (:require '[clojure.tools.trace :as trace]))\n</code></pre> <p>To trace a value returned from an expression, optionally adding a tag</p> <pre><code>(trace/trace  \"increments\" (map inc [1 2 3 4 5]))\n;;=&gt; TRACE increments: (2 3 4 5 6)\n;;=&gt; (2 3 4 5 6)\n</code></pre> <p>Trace a function call and its return value</p> <pre><code>(deftrace random-function [namespace] (rand-nth (vals (ns-publics namespace))))\n</code></pre> <p>Call the function to see the output of trace</p> <pre><code>(random-function 'clojure.core)\n;;=&gt; TRACE t1002: (random-function 'clojure.core)\n;;=&gt; TRACE t1002: =&gt; #'clojure.core/iteration\n;;=&gt; #'clojure.core/iteration\n</code></pre> <p>Trace functions can identify which form is failing</p> <pre><code>(trace/trace-vars practicalli.random-function/random-number)\n;;=&gt; #'practicalli.random-function/random-number\n</code></pre> <p>Call the function that is being traced and see the error</p> <pre><code>(practicalli.random-function/random-number 42)\n;;=&gt; TRACE t10951: (practicalli.random-function/random-number 42)\n;;=&gt; Execution error (ArithmeticException) at practicalli.random-function/random-number (random_function.clj:17).\n;;=&gt; Divide by zero\n</code></pre> <p>Dynamically trace all functions in the given name space</p> <pre><code>(trace-ns domain.namespace)\n</code></pre> <p>Or remove all function traces in a namespace</p> <pre><code>(untrace-ns domain.namespace)\n</code></pre> <p>Dynamically trace a given function</p> <pre><code>(trace-vars domain.namespace/function-name)\n ```\n\nRemove the trace on a given function\n\n```clojure\n(untrace-vars domain.namespace/function-name)\n</code></pre>"},{"location":"clojure-cli/repl-startup/","title":"Configure REPL on Startup","text":"<p>A Clojure REPL starts in the <code>user</code> namespace and automatically loads common tools to support REPL based development. </p> <p>When interacting with the REPL prompt directly, use <code>require</code> expressions to include additional functions into the <code>user</code> nameapace rather than use potentially complex commands to set the namespace.</p> Clojure REPL only starts in user namespace <p>The Clojure REPL only guarantees startup in the <code>user</code> namespace. There is no specific mechanism to start the REPL in any other namespace than <code>user</code>.</p> <p>Clojure CLI could use the general <code>--eval</code> flag as a hack to set a different namespace with an <code>in-ns</code> expression, although this may affect other tools and add complexity to the startup process.</p> Default REPL Tools <p>The Clojure REPL automatically loads common tools to support the foundation of a REPL driven workflow:</p> <p> clojure.repl namespace loads:</p> <ul> <li> apropos - function names fuzzy matching a given regex pattern</li> <li> dir - sorted list of public vars (functions) in a given namespace</li> <li> doc - doc-string of a give Clojure function / symbol </li> <li> find-doc - doc-string of matching functions, given a string or regex pattern</li> <li> source - source code of a given function</li> <li> pst print stack trace, optionally setting depth</li> </ul> <p> clojure.java.javadoc loads  javadoc to show the doc-string of Java methods</p> <p> clojure.pprint namepace loads  pp &amp;  pprint to return pretty printed (human friendly format) evaluation results</p>"},{"location":"clojure-cli/repl-startup/#custom-user-namespace","title":"Custom user namespace","text":"<p>Add a custom <code>user</code> namespace to further enhance the Clojure REPL workflow:</p> <ul> <li>load code into the REPL by requiring namespaces</li> <li>call functions to start services that support development, e.g. logging publisher, print REPL command help menu</li> <li>launch development tools - e.g. portal data inspector</li> <li>start components (i.e for mount, component, integrant)</li> <li>hotload libraries into the REPL process without restart (Clojure 1.12 onward)</li> </ul> <p>Create a project with custom user namespace</p> <p>Projects created with  Practicalli Project Templates contain a <code>dev/user.clj</code> file for configuring the REPL at start up.</p> <p>Practicalli custom user namespace supports the  Practicalli REPL Reloaded workflow</p> <p>Start the REPL with either the <code>:dev/env</code>, <code>:dev/reloaded</code> or <code>:repl/reloaded</code> alias from  Practicalli Clojure CLI Config to include <code>dev</code> directory on the class path and automatically load <code>dev/user.clj</code> code on REPL startup.</p>"},{"location":"clojure-cli/repl-startup/#define-user-namespace","title":"Define user namespace","text":"<p>A custom <code>user.clj</code> is typically placed in a <code>dev</code> folder within the root of the project, with the <code>dev</code> path defined in an alias to keep it separated from production code.</p> <p>Create a <code>dev/user.clj</code> file with a namespace called <code>user</code>.</p> dev/user.clj<pre><code>(ns user)\n</code></pre> <p>Create an alias to include the <code>dev</code> path when running a REPL process</p>  Practicalli Clojure CLI ConfigManual <p> Practicalli Clojure CLI Config includes aliases that add <code>dev</code> directory to the class path</p> <ul> <li><code>:dev/env</code> alias only adds the <code>dev</code> directory to the classpath</li> <li><code>:dev/reloaded</code> adds library hotload, namespace reload, porta data inspector and testing libraries &amp; <code>test</code></li> <li><code>:repl/reloaded</code> adds Rebel rich terminal UI to the tools provided by <code>:dev/reloaded</code></li> </ul> <p>Add an alias to the user <code>deps.edn</code> configuration, i.e. <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code></p> <p>Clojure User Config<pre><code> :env/dev\n  {:extra-paths [\"dev\"]}\n</code></pre> Review  Practicalli Clojure CLI Config for further alias examples.</p> <p>Run a Clojure REPL with the <code>:repl/reloaded</code> alias (or <code>:dev/reloaded</code> <code>:dev/env</code>)  to add the <code>dev</code> directory to the class path and load the code in <code>dev/user.clj</code> file into the REPL.</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Keep <code>user.clj</code> separate</p> <p>The <code>user.clj</code> code should not be included in live deployments, such as a jar or uberjar.  Including the <code>dev/</code> directory via an alias separates the <code>user.clj</code> from deployment actions.</p>"},{"location":"clojure-cli/repl-startup/#requiring-namespaces","title":"Requiring namespaces","text":"<p>Namespaces required in the <code>user</code> ns form will also be loaded. If a required namespace also requires namespaces, they will also be loaded into the REPL during startup.</p> <p>Functions <code>(defn)</code> and data <code>(def)</code> are immediately available.</p> <p>Require namespace in user ns expression</p> <p>Add a require expression to the namespace definition in <code>dev/user.clj</code> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.project-namespace]))\n</code></pre></p> Requiring a large number of libraries may slow REPL start up time <p>Require namespace in require expression</p> <p>If the library is not always required, place a <code>require</code> within a <code>(comment ,,,)</code> expression to be evaluated by the developer any time after REPL startup. dev/user.clj<pre><code>(ns user)\n\n(comment\n  (require '[practicalli.project-namespace])\n#_())\n</code></pre></p>"},{"location":"clojure-cli/repl-startup/#calling-functions","title":"Calling functions","text":"<p>Use the fully qualified function name from the required namespace can be called, to start the application for example.</p> <p>Example</p> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.project-namespace]))\n\n(practicalli.project-namespace/-main)\n</code></pre> <p>An alias can be used in the require expression, useful if multiple functions from a namespace are to be called</p> <p>Example</p> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.service :as service]))\n\n(service/-main)\n</code></pre>"},{"location":"clojure-cli/repl-startup/#repl-help-menu","title":"REPL Help menu","text":"<p>Printing a menu of functions provided by the custom user namespace helps with the usability of a project.</p> <p>Define a <code>help</code> function that prints out commands with a breif explination of their purpose.</p> <p>Add a <code>(help)</code> expression to call the help function on REPL startup, displaying the help menu. </p> <p>REPL Help menu</p> <pre><code>;; ---------------------------------------------------------\n;; Help\n\n(println \"---------------------------------------------------------\")\n(println \"Loading custom user namespace tools...\")\n(println \"---------------------------------------------------------\")\n\n(defn help\n  []\n  (println \"---------------------------------------------------------\")\n  (println \"System components:\")\n  (println \"(start)                        ; starts all components in system config\")\n  (println \"(restart)                      ; read system config, reloads changed namespaces &amp; restarts system\")\n  (println \"(stop)                         ; shutdown all components in the system\")\n  ;; (println \"(system)                       ; show configuration of the running system\")\n  ;; (println \"(config)                       ; show system configuration\")\n  (println)\n  (println \"Hotload libraries:             ; Clojure 1.12.x\")\n  (println \"(add-lib 'library-name)\")\n  (println \"(add-libs '{domain/library-name {:mvn/version \\\"v1.2.3\\\"}})\")\n  (println \"(sync-deps)                    ; load dependencies from deps.edn\")\n  (println \"- deps-* lsp snippets for adding library\")\n  (println)\n  (println)\n  (println \"Portal Inspector:\")\n  (println \"- portal started by default, listening to all evaluations\")\n  (println \"(inspect/clear)                ; clear all values in portal\")\n  (println \"(remove-tap #'inspect/submit)  ; stop sending to portal\")\n  (println \"(inspect/close)                ; close portal\")\n  (println)\n  (println \"(help)                         ; print help text\")\n  (println \"---------------------------------------------------------\"))\n\n(help)\n\n;; End of Help\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#log-publisher","title":"Log publisher","text":"<p>mulog is a very effective event log tool that also provides a range of log publishers.  A custom user namespace can be used to start mulog log publishers to directly support the development workflow</p> <ul> <li>pretty print console output for easier to read event messages</li> <li>custom tap-publisher to send all log message to a <code>tap&gt;</code> source, e.g. Portal data inspector</li> </ul> <p>Mulog configuration and publishers</p> <p>Require the mulog namespaces.</p> <p>Set the global context for all mulog events, setting common key/value pairs that appear in every event created after the global context was evaluated.</p> <p>Define a custom publisher to send all mulog events to the registered tap&gt; sources, e.g. Portal data inspector.</p> dev/mulog_events.clj<pre><code>;; ---------------------------------------------------------\n;; Mulog Global Context and Custom Publisher\n;;\n;; - set event log global context\n;; - tap publisher for use with Portal and other tap sources\n;; - publish all mulog events to Portal tap source\n;; ---------------------------------------------------------\n\n(ns mulog-events\n  (:require\n   [com.brunobonacci.mulog        :as mulog]\n   [com.brunobonacci.mulog.buffer :as mulog-buffer]))\n\n;; ---------------------------------------------------------\n;; Set event global context\n;; - information added to every event for REPL workflow\n(mulog/set-global-context! {:app-name \"todo-basic Service\",\n                            :version \"0.1.0\", :env \"dev\"})\n;; ---------------------------------------------------------\n\n;; ---------------------------------------------------------\n;; Mulog event publishing\n\n(deftype TapPublisher\n         [buffer transform]\n  com.brunobonacci.mulog.publisher.PPublisher\n  (agent-buffer [_] buffer)\n  (publish-delay [_] 200)\n  (publish [_ buffer]\n    (doseq [item (transform (map second (mulog-buffer/items buffer)))]\n      (tap&gt; item))\n    (mulog-buffer/clear buffer)))\n\n#_{:clj-kondo/ignore [:unused-private-var]}\n(defn ^:private tap-events\n  [{:keys [transform] :as _config}]\n  (TapPublisher. (mulog-buffer/agent-buffer 10000) (or transform identity)))\n\n(def tap-publisher\n  \"Start mulog custom tap publisher to send all events to Portal\n  and other tap sources\n  `mulog-tap-publisher` to stop publisher\"\n  (mulog/start-publisher!\n   {:type :custom, :fqn-function \"mulog-events/tap-events\"}))\n\n#_{:clj-kondo/ignore [:unused-public-var]}\n(defn stop\n  \"Stop mulog tap publisher to ensure multiple publishers are not started\n Recommended before using `(restart)` or evaluating the `user` namespace\"\n  []\n  tap-publisher)\n\n;; Example mulog event message\n;; (mulog/log ::dev-user-ns :message \"Example event message\" :ns (ns-publics *ns*))\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#reload-namespaces","title":"Reload Namespaces","text":"<p>The REPL state can become 'stale' and contain vars (data and function names) that are no longer part of the source code, especially after a code refactor.</p> <p>Rather than restart the repl, clojure.tools.namespace.repl provides functions that can clean the REPL state and reload changed namespaces from source code.</p> <p>Clojure Namespace Tools - reload</p> <p>Require the <code>clojure.tools.namespace.repl</code> namespace to access the <code>refresh</code> and <code>set-refresh-dirs</code> functions to support reloading of source code into a clean REPL state.</p> dev/user.clj<pre><code>(ns user\n  \"Tools for REPL Driven Development\"\n  (:require\n   [clojure.tools.namespace.repl :refer [set-refresh-dirs]]))\n</code></pre> <p>Use the <code>set-refresh-dirs</code> function to define directories to reload when calling <code>refresh</code>, effectively excluding <code>dev</code> and other directories by not including their names as arguments.</p> dev/user.clj<pre><code>;; ---------------------------------------------------------\n;; Avoid reloading `dev` code\n;; - code in `dev` directory should be evaluated if changed to reload into repl\n(println\n \"Set REPL refresh directories to \"\n (set-refresh-dirs \"src\" \"resources\"))\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#hotload-libraries","title":"Hotload libraries","text":"<p>Hotload is a way to add libraries to a running REPL process which were not include as a dependency during REPL startup.</p> Hotload libraries is SNAPSHOT feature - this guide will change when Clojure 1.12 is released <p>Functions to hotload libraries are part of the Clojure 1.12 development releases and an official feature as of the stable 1.12 release.</p> <p>For Clojure 1.11 and similar functions are available in the add-libs3 branch of the now deprecated <code>clojure.tools.deps.alpha</code> library.  </p> <p>clojure/tools.deps is the official library for all released functions from the alpha library</p> <p>This guide will be significantly rewritten once Clojure 1.12 is released.</p>  Practicalli Clojure CLI ConfigManual <p><code>:repl/reloaded</code>  and <code>dev/reloaded</code> aliases in  Practicalli Clojure CLI Config provide the <code>add-libs</code> function.</p> <p>Edit the project <code>deps.edn</code> configuration and add an <code>:lib/hotload</code> alias for the <code>clojure.tools.deps.alpha.repl</code> library.  Or add an alias to the user level configuration for use with any Clojure CLI project.</p> <p>The <code>add-libs</code> code is on a separate add-libs3 branch, so requires the SHA from the head of add-libs3 branch</p> <pre><code>  :lib/hotload\n  {:extra-deps {org.clojure/tools.deps.alpha\n               {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> <p>Alias example from  Practicalli Clojure CLI Config</p> <p>Start a REPL session using Clojure CLI with <code>:repl/reloaded</code>, <code>dev/reloaded</code> or <code>:lib/hotload</code> aliases</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Require and refer add-libs function</p> <p>Require the <code>clojure.tools.deps.alpha</code> library and refer the <code>add-libs</code> function.  The <code>add-libs</code> function can then be called without having to use an alias or the fully qualified name. <pre><code>(require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n</code></pre></p> <p>Hotload one or more libraries into the REPL using the <code>add-lib</code> function, including the fully qualified name of the library and version string.</p> <p>Hotload the hiccup library</p> <p>The hiccup library converts clojure structures into html, where vectors represent the scope of keywords that represent html tags. Load the hiccup library using add-libs <pre><code>(add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n</code></pre></p> <p>Require the hiccup library so its functions are accessible from the current namespace in the REPL. <pre><code>(require '[hiccup.core :as hiccup])\n</code></pre> Enter an expression using the <code>hiccup/html</code> function to convert a clojure data structure to html. <pre><code>(hiccup/html [:div {:class \"right-aligned\"}])\n</code></pre></p>"},{"location":"clojure-cli/repl-startup/#system-components","title":"System Components","text":"<p>Clojure has several library to manage the life-cycle of components that make up the Clojure system, especially those components with state. The order in which components are started and stopped can be defined to keep the system functioning correctly.</p> <p>Components can include an http server, routing, persistence, logging publisher, etc.</p> <p>Example system component management libraries included</p> <ul> <li>mount - manage system state in an atom</li> <li>integrant and Integrant REPL - data definition of system and init &amp; halt defmethod interface</li> <li>donut system</li> <li>component</li> </ul> <p>Require system namespace in user ns expression</p> <p>Require the system namespace and use <code>start</code>, <code>restart</code> and <code>stop</code> functions to manage the components in the system dev/user.clj<pre><code>(ns user\n  (:require [system]))\n\n(comment\n  (system/start)\n  (system/restart)\n  (system/stop)\n  )\n</code></pre></p> <p>Define code in the <code>dev/system.clj</code> file which controls the component life-cycle services library for the project.</p> <p>Create a <code>dev/system.clj</code> to manage the components, optionally using one of the system component management libraries.</p>"},{"location":"clojure-cli/repl-startup/#life-cycle-functions","title":"life-cycle functions","text":"<p>Start, stop and restart the components that a system is composed of, e.g. app server, database pool, log publisher, message queue, etc.</p> Atom restartMountIntegrant REPLDonut SystemComponent <p>Clojure web services run ontop of an HTTP server, e.g. http-kit, Jetty.</p> <p>A Clojure aton can be used to hold a reference to the HTTP server, allowing commands to stop that server.</p> <p>Use <code>clojure.tools.namespace.repl/refresh</code> when restarting the server (in between <code>stop</code> and <code>start</code>) to remove stale information in the REPL state.</p> <p>Restart an HTTP server for Clojure Web Service &amp; Refresh namespaces</p> dev/system_repl.clj<pre><code>;; ---------------------------------------------------------\n;; System REPL - Atom Restart \n;;\n;; Tools for REPl workflow with Aton reference to HTTP server \n;; https://practical.li/clojure-web-services/app-servers/simple-restart/\n;; ---------------------------------------------------------\n\n(ns system-repl\n  (:require \n    [clojure.tools.namespace.repl :refer [refresh]]\n    [practicalli.todo-basic.service :as service]))\n\n;; ---------------------------------------------------------\n;; HTTP Server State\n\n(defonce http-server-instance \n  (atom nil))  ; (1)! \n;; ---------------------------------------------------------\n\n;; ---------------------------------------------------------\n;; REPL workflow commands\n\n(defn stop\n  \"Gracefully shutdown the server, waiting 100ms.\n   Check if an http server isntance exists and \n   send a `:timeout` key and time in milliseconds to shutdown the server.\n   Reset the atom to nil to indicate no http server is running.\"\n  []\n  (when-not (nil? @http-server-instance)\n    (@http-server-instance :timeout 100) ; (2)!\n    (reset! http-server-instance nil)  ; (3)!\n    (println \"INFO: HTTP server shutting down...\")))\n\n(defn start\n  \"Start the application server and run the application,\n   saving a reference to the https server in the atom.\"\n  [&amp; port]\n  (let [port (Integer/parseInt\n              (or (first port)\n                  (System/getenv \"PORT\")\n                  \"8080\"))]\n    (println \"INFO: Starting server on port:\" port)\n\n    (reset! http-server-instance\n            (service/http-server-start port)))) ; (4)!\n\n\n(defn restart\n  \"Stop the http server, refresh changed namespace and start the http server again\"\n  []\n  (stop)\n  (refresh)  ; (5)! \n  (start))\n;; ---------------------------------------------------------\n</code></pre> <ol> <li> <p>A Clojure Aton holds a reference to the http server instance</p> </li> <li> <p>Shut down http server instance without stopping the Clojure REPL</p> </li> <li> <p>Reset the value in the atom to mil, indicating that no http server instance is running</p> </li> <li> <p>Reset the value in the atom to a reference for the running http server.  The reference is returned when starting the http server.</p> </li> <li> <p>Refresh the REPL state and reload changed namespaces from source code using <code>clojure.tools.namespace.repl/refresh</code></p> </li> </ol> <p>Define a <code>dev.clj</code> file with <code>go</code>, <code>stop</code> and <code>restart</code> functions that manage the life-cycle of mount components.  A <code>start</code> function contains the list of components with optional state.</p> <p>Require the mount namespace and the main namespace for the project, which should contain all the code to start and stop services.</p> dev/user.clj<pre><code>(ns user\n  :require [mount.core :refer [defstate]]\n           [practicalli.app.main])\n</code></pre> <p>Define a start function to start all services</p> dev/user.clj<pre><code>(defn start []\n  (with-logging-status)\n  (mount/start #'practicalli.app.conf/environment\n               #'practicalli.app.db/connection\n               #'practicalli.app.www/business-app\n               #'practicalli.app.service/nrepl))\n</code></pre> <p>The <code>go</code> function calls <code>start</code> and marks all components as ready.</p> dev/user.clj<pre><code>(defn go\n  \"Start all states defined by defstate\"\n  []\n  (start)\n  :ready)\n</code></pre> <p>The <code>stop</code> function stops all components, removing all non-persistent state.</p> <pre><code>(defn stop [] (mount/stop))\n</code></pre> <p>The reset function that calls <code>stop</code>, refreshes the namespaces so that stale definitions are removed and starts all components (loading in any new code).</p> dev/user.clj<pre><code>(defn reset\n  \"Stop all states defined by defstate.\n  Reload modified source files and restart all states\"\n  []\n  (stop)\n  (namespace/refresh :after 'dev/go))\n</code></pre> <p> Example dev.clj file for mount</p> <p>Use <code>dev</code> namespace during development</p> <p>Require <code>practicalli.app.dev</code> namespace rather than main, to start components in a development environment.</p> <p> Integrant REPL - Practicalli Clojure Web Services</p> <p>User manager - Integrant</p> <p>donut.system is a dependency injection library for Clojure and ClojureScript using system and component abstractions to organise and manage startup &amp; shutdown behaviour.</p> <p>Basic usage guide shows how to define a donut.system</p> <p><p> </p></p> <p>seancorfield/usermanager-example is an example project that uses Component for lifecycle management</p>"},{"location":"clojure-cli/repl-startup/#reference","title":"Reference","text":"<ul> <li>Mount project on GitHub</li> <li>Mount - collection of Clojure/Script mount apps</li> <li>donut.system</li> <li>Component</li> <li>A tutorial to Stuart Sierra's Component</li> <li>Refactoring to Components - Walmart Labs Lacinia</li> <li>Integrant</li> <li>Compojure and Integrant</li> <li>Build a Clojure web app using Duct - CircleCI</li> <li>Reloading Woes - Lambda island</li> </ul>"},{"location":"clojure-cli/projects/","title":"Clojure projects","text":"<p>Clojure CLI projects use a <code>deps.edn</code> file to specifies source paths and libraries required for the project to run.   </p> <p>alias are defined in the  <code>deps.edn</code> file to support development tasks, providing additional libraries, paths and tools. </p> <p>Generate a project from a template</p> <p>Create a project from a template for a consistent project structure and include commonly used libraries.</p> <p>Practicalli Project Templates create production grade projects providing a detailed starting point with configuration files for building and deploying the project.</p>"},{"location":"clojure-cli/projects/#create-minimal-project","title":"Create minimal project","text":"<p>Create a <code>deps.edn</code> file containing <code>{}</code> in the root of a directory for a minimal configuration.</p> <p>Create a <code>src</code> directory as the root of the source code, and <code>test</code> directory to contain unit test code.</p> Linux command to create a minimal clojure project <p>Run these Linux commands in the root of a directory to create a minimal Clojure project structure. <pre><code>touch deps.edn &amp;&amp; echo '{}' &gt; deps.edn &amp;&amp; mkdir src test\n</code></pre></p> <p>The project can now be run with a REPL via a terminal UI or Clojure aware Editor.</p> Migrate project to Clojure CLI <p>Guide to Migrating a project to Clojure CLI</p>"},{"location":"clojure-cli/projects/#project-structure","title":"Project Structure","text":"<p>The essence of most Clojure CLI projects contains the following files and directories.</p> path purpose deps.edn core project configuration, paths, dependencies and aliases build.clj build specific configuration, create jars and uberjars src root directory of Clojure source files test root directory for Clojure test source files README.md Description of the project and how to develop / maintain it CHANGELOG.md Meaningful history of changes to the project organised by release .git Local git repository and configuration .gitignore Git ignore patterns for the project <p>Example deps.edn configuration file</p> <pre><code>{:paths\n [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure    {:mvn/version \"1.11.1\"}}\n  http-kit/http-kit      {:mvn/version \"2.6.0\"}  \n  metosin/reitit         {:mvn/version \"0.5.13\"}\n  com.brunobonacci/mulog {:mvn/version \"0.9.0\"}\n\n :aliases\n {;; Clojure.main execution of application\n  :run/service\n  {:main-opts [\"-m\" \"practicalli.donuts.service\"]}\n\n  ;; Clojure.exec execution of specified function\n  :run/greet\n  {:exec-fn   practicalli.donuts.service/greet\n   :exec-args {:name \"Clojure\"}}\n\n  ;; Add libraries and paths to support additional test tools\n  :test/env\n  {}\n\n  ;; Test runner - local and CI\n  ;; call with :watch? true to start file watcher and re-run tests on saved changes\n  :test/run\n  {:extra-paths [\"test\"]\n   :extra-deps  {lambdaisland/kaocha {:mvn/version \"1.85.1342\"}}\n   :main-opts   [\"-m\" \"kaocha.runner\"]\n   :exec-fn     kaocha.runner/exec-fn\n   :exec-args   {:randomize? false\n                 :fail-fast? true}}\n\n  ;; tools.build `build.clj` built script\n  :build\n  {:replace-paths [\".\"]\n   :replace-deps  {io.github.clojure/tools.build\n                   {:git/tag \"v0.9.4\" :git/sha \"76b78fe\"}}\n   :ns-default    build}}}\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/","title":"Add libraries to a project","text":"<p>The project <code>deps.edn</code> file is used to add specific versions of libraries to a project.</p> <p>The <code>:deps</code> top-level key defines libraries that are always included, e.g when starting the REPL or packaging a project in an Uberjar.</p> <p>Aliases are defined to include libraries only when the alias name is included, e.g. <code>:dev/reloaded</code> alias includes several libraries only relevant during development of a Clojure project.</p> <p>There are thousands of community Clojure and ClojureScript libraries available via clojars.org and Maven Central.</p> <p><code>:deps</code> top level key contains a hash-map of dependencies, each dependency of the form <code>domain/name {:mvn/version \"version-number\"}</code></p> Project deps.edn<pre><code>{:deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}\n  hiccup/hiccup       {:mvn/version \"2.0.0-alpha2\"}}}\n</code></pre> Finding libraries <p>Search for community libraries via the Clojars.org website or visit the Clojure Toolbox to browse some of the community libraries available</p> <p><code>clojure -M:search/libraries pattern</code> where pattern is the name of the library to search for.  Copy the relevant results into the project <code>deps.edn</code> file.</p> <p><code>clojure -M:search/libraries --format:merge pattern</code> will automatically add the library into the <code>deps.edn</code> file.</p> <p><code>clojure -X:deps find-versions :lib fully.qualified/library-name :n 5</code> returns the last 5 versions of the given library.</p>"},{"location":"clojure-cli/projects/add-libraries/#alias-libraries","title":"Alias libraries","text":"<p><code>:aliases</code> top-level key contains a hash-map of alias definitions.</p> <p>Each alias has a unique name with <code>:aliases</code> and is represented by a Clojure keyword associated with a Clojure hash-map, <code>{}</code></p> <p><code>:extra-deps</code> keyword is associated with hash-map that contains one or more fully qualified library names and the version of the library to use.  The version of the library is defined with the maven form <code>{:mvn/version \"0.4.2\"}</code> or Git form <code>{:git/url \"https://github.com/clojure/tools.deps.alpha\" :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}</code></p> <p>The following example can be added to a project <code>deps.edn</code>, within the <code>:aliases {}</code> form.</p> deps.edn alias definition with maven and git versions<pre><code>:dev/reloaded\n{:extra-deps {djblue/portal {:mvn/version \"0.34.2\"}\n              lambdaisland/kaocha {:mvn/version \"1.71.1119\"}\n              org.clojure/test.check {:mvn/version \"1.1.1\"}\n              org.clojure/tools.namespace {:mvn/version \"1.3.0\"}\n              org.clojure/tools.deps.alpha {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                                            :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> <p>When the alias is included in the command to start the REPL, the libraries are placed on the class path and can be required for use.</p> <pre><code>clojure -M:dev/reloaded:repl/rebel\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/#hotload-libraries","title":"Hotload libraries","text":"<p><code>add-libs</code> is a function to load one or more libraries into a running REPL, negating the need to restart the REPL process.</p> <p>Start a REPL process with <code>clojure -M:repl/reloaded</code> to include the add-libs librar. Alternatively, include <code>:dev/reloaded</code> or <code>:lib/hotload</code> alias with any Clojure command to start a REPL.</p> <p>Hotload Libraries explained</p> <p>REPL Reloaded - Hotload Libraries details all the options for including the clojure.tools.deps.alpha library that contains the <code>add-libs</code> function</p> <p>Use a rich comment block or a <code>dev/user.clj</code> file to require the <code>clojure.tools.deps.alpha.repl</code> namespace and write <code>add-libs</code> expressions to hot-load libraries.</p> <p>A rich comment block ensures <code>add-libs</code> code is only evaluated manually by a developer.</p> <pre><code>(comment\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n)\n</code></pre> rich-comment-hotload Clojure LSP snippet <p>Snippets provided by Clojure LSP include <code>rich-comment-hotload</code>, to add a rich comment block with a require for <code>clojure.tools.deps.alpha</code> and an <code>add-libs</code> expression, making it very quick to add this code.</p> <p><code>deps-maven</code> and <code>deps-git</code> snippets help ensure the correct syntax is used for the <code>add-libs</code> expression for each library dependency to be added.</p> <p>Practicalli Clojure LSP Config contains a wide range of snippets</p>"},{"location":"clojure-cli/projects/add-libraries/#hotload-example","title":"Hotload Example","text":"<p>Create a web server from scratch, serving pages generated from hiccup, with all libraries hot-loaded as the code is being written.  Demonstrates that it is possible to write an application when only starting the REPL once.</p> Web server from scratch <pre><code>(comment\n  ;; run REPL with :lib/hotload alias\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n\n  ;; hotload the libraries required for the server\n  (add-libs\n    '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n  ;; =&gt; (http-kit/http-kit)\n\n\n  ;; Require the namespace from the http-kit library\n  (require '[org.httpkit.server :as app-server])\n\n   ;; Define a handler for http requests\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server with the handler\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  ;; Create a page template\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ;; Visit http://localhost:8888/ and refresh the page to see the new welcome-page\n  )\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/#excluding-dependencies","title":"Excluding dependencies","text":"<p>Adding several libraries as dependencies to a project may cause conflicts. The <code>:exclusions</code>  key will prevent libraries within a library dependency from being included in the project</p> <p>For example, library-a and library-b both have a dependency on library-c, as defined in the project configuration for library-a and library-b.  When including library-a and library-b in the project as dependencies, there could be a conflict if the both libraries use a different version of library-c.  Adding an exclude to library-a or library-b will stop library-c being included twice.</p> <p>A Library that is self-contained and does not itself include any dependencies on any other libraries is unlikely to cause conflicts.  Using these self-contained libraries simplifies the overall application design.</p> <pre><code>{:deps {:org.clojure/clojure {:mvn/version \"1.10.2\"}\n        :cheshire/cheshire  {:mvn/version \"5.10.0\"\n            :exclusions \"com.fasterxml.jackson.core/jackson-core\"}}}\n</code></pre>"},{"location":"clojure-cli/projects/hotload-in-project/","title":"Hotload libraries in Clojure Projects","text":"<p>When starting a REPL process the dependencies listed in the project <code>deps.edn</code> file are added to the class path.  To add further dependencies the REPL has to be  restarted to include new libraries added to the <code>deps.edn</code> file.</p> <p></p> <p>Practicalli REPL Reloaded workflow allows new dependencies to be added to a running REPL process, negating the need to restart the REPL process which would loose the current REPL state.</p>"},{"location":"clojure-cli/projects/hotload-in-project/#hotload-repl","title":"Hotload REPL","text":"<p>Start a REPL with an alias that includes the <code>add-libs</code> library.</p> Terminal REPLClojure Editor <p>Start a terminal  REPL with the <code>:repl/reloaded</code> alias and connect</p> <p><pre><code>clojure -M:repl/reloaded\n</code></pre> Connect to the REPL process from a Clojure editor for an enhanced development experience.</p> <p>Run a Clojure REPL from the editor (jack-in command) configured with the <code>:dev/reloaded</code> alias or <code>:lib/hotload</code> alias in an Editor jack-in command or other REPL startup command.</p> <p>Alternatively, run a Terminal REPL and connect the editor to that REPL process (connect command)</p> <p>Practicalli REPL Reloaded Configuration</p>"},{"location":"clojure-cli/projects/hotload-in-project/#rich-comment-block","title":"Rich Comment Block","text":"<p>Use a rich comment block or a <code>dev/user.clj</code> file to require the <code>clojure.tools.deps.alpha.repl</code> namespace and write <code>add-libs</code> expressions to hot-load libraries.</p> <p>A rich comment block ensures <code>add-libs</code> code is only evaluated manually by a developer.</p> <pre><code>(comment\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n)\n</code></pre> Rich-comment-hotload <p>Practicalli Clojure LSP Config includes the <code>rich-comment-hotload</code> snippet which adds a rich comment block with a require for <code>clojure.tools.deps.alpha</code> and an <code>add-libs</code> expression, making it very quick to add this code.</p> <p><code>deps-maven</code> and <code>deps-git</code> snippets help ensure the correct syntax is used for the <code>add-libs</code> expression for each library dependency to be added.</p>"},{"location":"clojure-cli/projects/hotload-in-project/#hotload-example","title":"Hotload Example","text":"<p>Create a web server from scratch, serving pages generated from hiccup, with all libraries hot-loaded as the code is being written.  Demonstrates that it is possible to write an application when only starting the REPL once.</p> <pre><code>(comment\n  ;; run REPL with :lib/hotload alias\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n\n  ;; hotload the libraries required for the server\n  (add-libs\n    '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n  ;; =&gt; (http-kit/http-kit)\n\n\n  ;; Require the namespace from the http-kit library\n  (require '[org.httpkit.server :as app-server])\n\n   ;; Define a handler for http requests\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server with the handler\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  ;; Create a page template\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ;; Visit http://localhost:8888/ and refresh the page to see the new welcome-page\n  )\n</code></pre> Using add-libs with project deps.edn <p>A project <code>deps.edn</code> file can also be used to hotload libraries with <code>add-lib</code>.  This has the advantage that newly added libraries become part of the normal project dependency configuration.</p> <p>Add a namespace definition to the <code>deps.edn</code> file to help editors understand the <code>deps.edn</code> file is being used for code.  Use the <code>#_</code> comment reader macro with the namespace definition to only evaluate this code manually as a developer.</p> <p>Add the <code>add-libs</code> expression after the <code>:deps</code> key so that it is easy to slurp in the existing and new dependencies as a single hash-map.  Use the comment reader macro <code>#_</code> to only evaluate this code manually.</p> <p>To hotload, remove the <code>#_</code> temporarily and slurp in the hash-map of dependencies, placing a <code>'</code> at the start of the hash-map.  Add the name and version of libraries to hotload in the hash-map.  Evaluate the <code>add-libs</code> expression which should return a list of new namespaces added.</p> <p>Once hotload has finished, barf the hash-maps of dependencies from the <code>add-libs</code> expression, removing the <code>'</code>.  Add the <code>#_</code> to the <code>add-libs</code> expression and save the file.</p> <p>The hotloaded libraries are now available by requiring their namespaces.  If the REPL is restarted, the new dependencies will be included in the Classpath as they are now part of the project configuration.</p> <pre><code>;; ---------------------------------------\n;; Project Configuration with  Hotload\n;; ---------------------------------------\n\n;; Hotload requires\n#_(ns deps.edn\n    (:require [clojure.tools.deps.alpha.repl :refer [add-libs]]))\n\n;; Project configuration\n{:paths\n [\"src\" \"resources\"]\n\n :deps\n #_ (add-libs)\n {org.clojure/clojure {:mvn/version \"1.10.1\"}\n  http-kit/http-kit   {:mvn/version \"2.5.1\"}\n  hiccup/hiccup       {:mvn/version \"2.0.0-alpha2\"}}\n\n :aliases {}\n</code></pre>"},{"location":"clojure-cli/projects/hotload-in-project/#live-coding-video","title":"Live Coding video","text":"<p>See the REPL driven development video by Sean Corfield for this technique.</p> <p> </p> <p>Jump to 23 minutes into the video to see this form of hotload in action.</p>"},{"location":"clojure-cli/projects/migrate-project/","title":"Migrating Project To Clojure CLI","text":"<p>Migrating an existing project to Clojure CLI can be as simple as the addition of a <code>deps.edn</code> configuration file.</p> <p>Leiningen plugins that change code</p> <p>A few Leiningen plugins inject code into a project to make it work.  For example, lein-ring injects Clojure code into the project to run an application server.  These type of plugins may require updates to the Clojure code in the project.</p>"},{"location":"clojure-cli/projects/migrate-project/#minimal-approach","title":"Minimal approach","text":"<p>Create a <code>deps.edn</code> file in the root of the project directory, containing an empty hash-map, <code>{}</code></p> <p>The Clojure version will be taken from the Clojure CLI tools install configuration.</p> <p>This configuration is enough to run a terminal REPL UI for the project, although requiring namespaces from the project may require libraries to be added as dependencies first.</p>"},{"location":"clojure-cli/projects/migrate-project/#adding-dependencies","title":"Adding dependencies","text":"<p>All Clojure projects require the <code>org.clojure/clojure</code> library and a specific version is defined in the configuration that comes with the Clojure CLI install.</p> <p>Use the <code>:deps</code> key in <code>deps.edn</code> to specify a version of the <code>org.clojure/clojure</code> library, along with any dependencies required for the Clojure code to run.</p> <pre><code>{:deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}\n  integrant/integrant {:mvn/version \"0.8.0\"}}}\n</code></pre> REPL Reloaded - add-libs hotload dependencies <p>Practicalli REPL Reloaded provides the add-libs function that can hotload libraries into the running REPL, without having to restart the REPL process.</p> <p>The hotload approach can also be useful for diagnosing conflicts in dependencies by loading them in stages to narrow down the library causing the conflict.</p>"},{"location":"clojure-cli/projects/migrate-project/#adding-paths","title":"Adding paths","text":"<p>It is advisable to specify the directory paths to define the location of the source code in the project, especially when running the project in other environments such as a continuous integration server.</p> <p>Edit the <code>deps.edn</code> file in the root of the project directory and add source directory and if relevant the resources directory.</p> <pre><code>{:paths\n   [\"src\" `resource`]}\n</code></pre>"},{"location":"clojure-cli/projects/migrate-project/#add-test-runner","title":"Add test runner","text":"<p>Tests can be run locally using the <code>:test/run</code> or <code>:test/watch</code> aliases from the  Practicalli Clojure CLI Config.</p> Continuous Integration Support <p>A Continuous Integration server requires an alias in the project <code>deps.edn</code> file to define a test runner.</p> <p>A selection of test runners are provided via aliases defined in  Practicalli Clojure CLI Config.  Copy a test runner alias to the project <code>deps.edn</code> file.</p>"},{"location":"clojure-cli/projects/migrate-project/#deployment","title":"Deployment","text":"<p>A Continuous Delivery pipeline will require an alias in the project <code>deps.edn</code> file to define how to build a jar or uberjar to package the Clojure project.</p> <p>Project Package section details how to use <code>tools.build</code> to create jar and uberjar archives of the project for deployment.</p>"},{"location":"clojure-cli/projects/migrate-project/#migration-tools","title":"Migration Tools","text":"<p>Several tools exist to support migration from Leiningen projects to Clojure CLI projects.  Results will be dependant on how complex the Leiningen project configuration is.</p> <ul> <li>lein-to-deps - create a <code>deps.edn</code> configuration from a <code>project.clj</code> configuration</li> <li>lein-tools-deps - share Clojure CLI dependencies with Leiningen project configuration.</li> </ul>"},{"location":"clojure-cli/projects/namespace/","title":"Namespaces","text":"<p>Using namespaces  makes code easier to work with by provide levels of abstraction that convey the overall design of the project.  Clearly organized namespaces support a simple design approach for a project and make it easier to maintain.</p> <p>A namespace is a logical separation of code, usually along features of the projects. Think of all namespaces as creating an API's within the project that communicate the architecture of the system.</p> <p></p>"},{"location":"clojure-cli/projects/namespace/#controlling-scope","title":"Controlling scope","text":"<p>Logically related data structures and functions are defined within a namespace, limiting their default scope to that namespace.</p> <p>Namespaces should limit their interdependence on each other (limited number of required namespaces) to avoid a highly coupled design.</p> <p>Within a namespace a var (<code>def</code>, <code>defn</code>) can be called by its short-form name.  Outside of the namespace, a fully qualified name must be used, or required via an alias or directly referred.</p> <p>Vars can be marked as private, <code>def ^private name</code>, so they can be accessed only by functions in their own namespace (athough there are ways to by-pass that scope restiction).</p>"},{"location":"clojure-cli/projects/namespace/#including-another-namespace","title":"Including another namespace","text":"<p><code>(ns namespace.name (:require [domain/filename :as purpose]))</code> is used to enable access to the functions &amp; named data structures in another namespace than the current one.  The included namespace is given an alias so its clear which code comes from that namespace.</p> <p>Practicalli recommends using a meaningful alias that defines the purpose of the library you are including.  This helps with the understanding and maintainability of the code, especially if you wish to refactor and replace the included library with an alternative.  An alias name should be meaningful and you should avoid single character and cryptic aliases.</p> <pre><code>(ns my-namespace.core\n  :require [clojure.java.io :as java-io])\n\n(defn read-the-file [filename]\n  (line-seq (java-io/reader filename)))\n\n(read-the-file \"project.clj\")\n</code></pre> <p>Trying out a namespace</p> <p><code>(require '[domain/filename])</code> can be used within you code if testing that namespace functions to see if they are useful to the project.  Using a live linter such as clj-kondo, part of Clojure LSP, will highlight missing namespaces.</p>"},{"location":"clojure-cli/projects/namespace/#including-specific-parts-of-a-namespace","title":"Including specific parts of a namespace","text":"<p><code>:refer</code> in the <code>require</code> expression includes one or more specific vars directly in the current namespace, as if it had been defined there. Referring a var means it no longer requires a namespace qualifier.</p> <p>Use <code>:refer</code> when the library being required the predominant focus of that namespace. A good example is <code>clojure.test</code> which is included to specifically write unit tests.</p> <pre><code>(ns practicalli.gameboard.handler-test\n  :require\n    [clojure.test :refer [deftest is testing]]\n    [practicalli.gameboard.handler :as handler])\n\n(deftest highscore-test\n  (testing \"A description of the test\"\n    (is (true? (handler/public-function 42)))))\n</code></pre> <p>(deftest public-function-in-namespace-test   (testing \"A description of the test\"     (is (= 1 (public-function arg)))     (is (predicate-function? arg))))</p> Rarely used options - include exclude rename vars <p>These other options on required functions are rarely used in practice.  They tend to cause more issues than they solve, so use with care.</p> <p><code>:exclude</code> will prevent a var from being used from a required namespace.</p> <p><code>:only</code> will include only that var from the required namespace.</p> <p><code>:rename</code> changes the name of the original function, if there conflicts</p>"},{"location":"clojure-cli/projects/namespace/#adding-multiple-namespaces","title":"Adding multiple namespaces","text":"<p>The idiom in Clojure is to include multiple namespaces with just one <code>:require</code> statement</p> <p>Here is an example namespace expression with multiple require statements from the duct web framework template</p> <pre><code>(ns duct-test.main\n  (:require [clojure.java.io :as io]\n            [com.stuartsierra.component :as component]\n            [duct.middleware.errors :refer [wrap-hide-errors]]\n            [meta-merge.core :refer [meta-merge]]\n            [duct-test.config :as config]\n            [duct-test.system :refer [new-system]]))\n</code></pre> <p>Avoid use form - require should be used</p> <p>The <code>use</code> or <code>:use</code> form is not recommended as it pulls in everything the namespace and everything that the included namespace also included.  This can lead to conflicts, especially in larger projects.</p> <p>As Clojure is typically composed of many libraries, its prudent to only include the specific things you need from another namespace.</p>"},{"location":"clojure-cli/projects/namespace/#design-refactor","title":"Design &amp; Refactor","text":"<p>When starting a new project all the code is typically in one namespace, unless you are using a template that creates multiple namespaces with sample code.</p> <p>Practicalli recommends adding comment sections as the code is developed, grouping code by its purpose.  As the namespace grows in size and complexity, these groups can be moved into their own namespaces as necessary.  A code refactor is much simpler as the code is already grouped logically by purpose.</p> Code comment sections <pre><code>;; --------------------------------------------------\n;; State\n\n;; --------------------------------------------------\n\n;; --------------------------------------------------\n;; Helper functions\n\n;; --------------------------------------------------\n\n;; --------------------------------------------------\n;; System / Lifecycle\n\n;; --------------------------------------------------\n</code></pre> <p>Clojure LSP Snippets</p> <p>Practicalli Clojure LSP Config defines snippets to create sections within a Clojure file</p> <p><code>comment-header</code> to describe the overall purpose of the namespace</p> <p><code>comment-section</code> creates a start and end comment line and text comment</p> <p>One pass evaluation</p> <p>A Clojure file is evaluated from top to bottom, so var (<code>def</code>, <code>defn</code>) definitions should come before they are used in the code.</p>"},{"location":"clojure-cli/projects/rich-comments/","title":"Rich Comments","text":"<p>The <code>(comment ,,,)</code> form is commonly used to contain living experimental code, so it is often referred to as a rich comment as its purpose is more than just commenting out code.</p>"},{"location":"clojure-cli/projects/rich-comments/#experimental-design","title":"Experimental design","text":"<p>Whilst iterating through designs, much experimental code can be created which is not (yet) ready to be part of the main namespace.</p> <p>Experimental code can be written in a <code>(comment ,,,)</code> form to keep it separate from more finalised implementations.</p> <p>When a namespace is evaluted, code within the <code>(comment ,,,)</code> form is not automatically loaded.</p> <p>Most editors support evaluation of Clojure code within the <code>(comment ,,,)</code> form, allowing a range of design implementations to be evaluated against each other.</p> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <p>Practicalli Clojure LSP Config - rich-comment-hotload snippet</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n\n  (def data-model {:nested {:hash \"map\" :design \"choice\"}})\n  (def data-model [{:collection \"of\" :hash \"maps\" :design \"choice\"}\n                   {:collection \"of\" :hash \"maps\" :design \"choice\"}])\n\n  (defn value-added-tax []\n    ;; algorithm - initial design)\n\n  (defn value-added-tax []\n    ;; algorithm - alternate design)\n\n  ) ; End of rich comment block\n</code></pre>"},{"location":"clojure-cli/projects/rich-comments/#design-journal","title":"Design Journal","text":"<p>When the problem domain or libraries selected are relatively unknown, a significant amount of learning and experimentation may be required.  This learning can be captured in a separate namespace, often referred to as a design journal.</p> <p>Creating a journal of the decisions made as code is designed makes the project easier to understand and maintain.  Journals avoid the need for long hand-over or painful developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A design journal can be added as a <code>(comment ,,,)</code> section at the bottom of each namespace, or more typically in its own namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Practicalli example journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"clojure-cli/projects/rich-comments/#snippets","title":"Snippets","text":"<p>clojure-lsp contains a number of snippets to create variations of a comment form.</p> <ul> <li><code>rich-comment</code> a basic comment form</li> <li><code>rich-comment-rdd</code> comment form that informs clj-kondo to ignore duplicate function definitions, avoids warnings when testing multiple implementations of the same function</li> <li><code>rich-comment-hotload</code> - comment form with Clojure CLI library hotloading</li> </ul>"},{"location":"clojure-cli/projects/rich-comments/#migrating-design-to-tests","title":"Migrating design to tests","text":"<p>REPL code experiements within rich comment blocks are often a good source of code that can be converted into formal unit tests.</p> <p>Example values used to test functions as they are designed can be useful to create meaningful sets of test data, especially when testing edge conditions.</p>"},{"location":"clojure-cli/projects/rich-comments/#live-examples","title":"Live examples","text":"<p>A rich comment at the end of a namespace can include code that demonstrates how to use the key aspects of the namespace API.</p> <p></p>"},{"location":"clojure-cli/projects/package/","title":"Package with Clojure tools.build","text":"<p>The  Clojure.org tools.build project is used to build jar files to deploy libraries and uberjar files to run deployed projects (e.g. in Docker containers or directly on an Operating System with Java JVM installed).</p> <p>Clojure tools.build is a library to define build related tasks using Clojure code.</p> <p>Practicalli Project Templates includes tools.build configuration</p> <p>Clojure projects created with Practicalli Project Templates include a <code>build.clj</code> configuration to build an uberjar of the project.</p> <p>The <code>make build-jar</code> runs the <code>clojure -T:build jar</code> command to build an uberjar.</p> Java ARchive - jar file <p>A <code>.jar</code> file is a zip archive of the project containing all the files for running a Clojure project.  The archive should contain metatdata files such as Manifest and pom.xml and can contain Clojure sources or compiled class files from the project (or both).</p> <p>An ubjerjar is <code>.jar</code> file that also contains all the project dependencies including Clojure.  The uberjar is a self-contained file that can be easily deployed and requires only a Java run-time (Java Virtual Machine), using the <code>java -jar project-uberjar.jar</code> command, with the option to pass arguments to the Uberjar also.</p> Practicalli Project Build tasksClojure tools.build <p> Practicalli Project templates include a <code>build.clj</code> configuration with <code>jar</code> and <code>uberjar</code> tasks.</p> <p>Create a runnable Clojure archive</p> <pre><code>clojure -T:project/build uberjar\n</code></pre> <p>Create a Clojure library archive</p> <pre><code>clojure -T:project/build jar\n</code></pre> <p>tools.build provides an API for pragmatically defining tasks to build Clojure projects.</p> <p>Create a <code>build.clj</code> configuration with tasks for building a library jar or runable uberjar.</p> <p> Define build.clj configuration for tools.build</p>"},{"location":"clojure-cli/projects/package/tools-build/","title":"Package projects with tools.build","text":"Improved build script examples have been added <p>Please report any issues using the new examples</p> <p> Clojure.org tools.build is a library to define build related tasks using Clojure code.</p> <p>The  tools.build API provides a consistent interface to access the project configuration (project basis) and common tasks that facilitate building and packaging projects.</p> <p>Include a build alias and build script in each project to make use of Clojure tools.build:</p> <ul> <li><code>:build/task</code> alias adding tools.build library to the class path in the project <code>deps.edn</code> file</li> <li><code>build.clj</code> defines a namespace requiring tools.build, a project configuration and functions as build tasks</li> </ul> Practicalli Project Templates include tools.build tasks <p> Practicalli Project templates include a <code>build.clj</code> tasks to generate a library <code>jar</code> or a service <code>uberjar</code>.</p>"},{"location":"clojure-cli/projects/package/tools-build/#define-build-alias","title":"Define build alias","text":"<p>Add an alias to the project <code>deps.edn</code> file which includes the <code>org.clojure/tools.build</code> project.</p> <p>:build/task alias created by Practicalli Project Templates</p> Project deps.edn<pre><code>  ;; tools.build `build.clj` built script\n  :build/task\n  {:replace-paths [\".\"]\n   :replace-deps {io.github.clojure/tools.build\n                  {:git/tag \"v0.9.6\" :git/sha \"8e78bcc\"}}\n   :ns-default build}\n</code></pre> <p>Use Clojure CLI to run any of the tasks defined in the <code>build</code> namespaces.</p> <pre><code>clojure -T:build/task task-name\n</code></pre> tools.build release information <p>Clojure.org tools.build release information shows the current values for <code>git/tag</code> and <code>:git/sha</code></p> Developing code in the build script <p><code>:replace-paths [\".\"]</code> includes the <code>build.clj</code> file on the class path to allow for REPL development of the build tasks</p> <p>Include <code>:build</code> alias in the Clojure command when starting the REPL. <pre><code>clojure -M:build/task:repl/rebel\n</code></pre></p>"},{"location":"clojure-cli/projects/package/tools-build/#build-script","title":"Build Script","text":"<p>Create a <code>build.clj</code> file which defines a namespace requiring tools.build, a project configuration and functions as build tasks</p> <p>An Uberjar file is built to deploy a Clojure service, e.g. in test, staging or production environment.</p> <p>A Jar file is built to published a Clojure library to a Maven repository, e.g. Clojars.org, Maven Central or a private Maven repository.</p>"},{"location":"clojure-cli/projects/package/tools-build/#namespace-definition","title":"Namespace definition","text":"<p>Define the namespace and require the clojure.tools.build.api and any additional libraries.</p> Service UberjarLibrary Jar <p>Namespace definition with tools.build.api and Pretty Print</p> build.clj<pre><code>(ns build\n  (:require\n   [clojure.tools.build.api :as build-api]\n   [clojure.pprint :as pprint]))\n</code></pre> <p>Namespace definition with tools.build.api and Pretty Print</p> build.clj<pre><code>(ns build\n  (:require\n   [clojure.tools.build.api :as build-api]\n   [deps-deploy.deps-deploy :as deploy-api]\n   [clojure.pprint :as pprint]))\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#build-configuration","title":"Build configuration","text":"<p>Define a hash-map containing keys and values required to build the project.</p> Service UberjarLibrary Jar <p>Define a project configuration for building an Uberjar file to run a service using the <code>java -jar</code> command.</p> <p>The Uberjar can be deployed to run the service in test, staging and production environments.</p> <p>Clojure Service build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Project configuration\n\n(def project-config\n  \"Project configuration to support build tasks\"\n  {:class-directory \"target/classes\"\n   :main-namespace  'practicalli/project-name/service\n   :project-basis   (build-api/create-basis)\n   :uberjar-file    \"target/practicalli-servicename-standalone.jar\"})\n\n(defn config\n  \"Display build configuration\"\n  [config]\n  (pprint/pprint (or config project-config)))\n\n;; End of Build configuration\n;; ---------------------------------------------------------\n</code></pre> <p>Define a project configuration for building a jar file for deployment on Clojars and Maven Central, or a private repository. </p> <ul> <li><code>pom-template</code> is the standard structure for generating a pom.xml file, required by Maven repositories, i.e. Clojars.org and Maven Central</li> <li><code>project-config</code> specific values for building the project, e.g. name, version, etc.</li> <li><code>config</code> function to pretty print the build configuration</li> </ul> <p>Clojure Library build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build configuration\n\n(defn- pom-template\n  \"Standard structure for a `pom.xml` file, a Maven project configuration \n  required to deploy libraries to Clojars.org, Maven Central or private Maven repositories\n  https://maven.apache.org/guides/introduction/introduction-to-the-pom.html\"\n  [project-version]\n  [[:description \"FIXME: add purpose of library.\"]\n   [:url \"https://github.com/organisation/project-name\"]\n   [:licenses\n    [:license\n     [:name \"Creative Commons Attribution-ShareAlike 4.0 International\"]\n     [:url \"https://creativecommons.org/licenses/by-sa/4.0/\"]]]\n   [:developers\n    [:developer\n     [:name \"Organisation name\"]]]\n   [:scm\n    [:url \"https://github.com/organisation/project-name\"]\n    [:connection \"scm:git:https://github.com/organisation/project-name.git\"]\n    [:developerConnection \"scm:git:ssh:git@github.com:organisation/project-name.git\"]\n    [:tag (str \"v\" project-version)]]])\n\n\n(def project-config\n  \"Project configuration to support build tasks\"\n  (let [library-name 'net.clojars.organisation/project-name\n        version \"0.1.0-SNAPSHOT\"]\n    {:library-name     library-name\n     :project-version  version\n     :jar-file         (format \"target/%s-%s.jar\" (name library-name) version)\n     :project-basis    (build-api/create-basis)\n     :class-directory  \"target/classes\"\n     :src-directory    [\"src\"]\n     :target-directory \"target\"\n     :pom-config       (pom-template version)}))\n\n\n(defn config\n  \"Display build configuration\"\n  [config]\n  (pprint/pprint (or config project-config)))\n;; End of Build configuration\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#build-task","title":"Build Task","text":"Service UberjarLibrary Jar <p>Define Clojure functions to run the required build tasks</p> <ul> <li><code>clean</code> to remove build artefacts, e.g. <code>target</code> directory</li> <li><code>Uberjar</code> creates a Jar file for a Clojure library, ready for publishing</li> </ul> <p>Clojure Service build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build tasks\n\n(defn clean\n  \"Remove a directory\n  - `:path '\\\"directory-name\\\"'` for a specific directory\n  - `nil` (or no command line arguments) to delete `target` directory\n  `target` is the default directory for build artefacts\n  Checks that `.` and `/` directories are not deleted\"\n  [directory]\n  (when\n   (not (contains? #{\".\" \"/\"} directory))\n   (build-api/delete {:path (or (:path directory) \"target\")})))\n\n\n(defn uberjar\n  \"Create an archive containing Clojure and the build of the project\n  Merge command line configuration to the default project config\"\n  [options]\n  (let [config (merge project-config options)\n        {:keys [class-directory main-namespace project-basis uberjar-file]} config]\n    (clean \"target\")\n    (build-api/copy-dir {:src-dirs   [\"src\" \"resources\"]\n                         :target-dir class-directory})\n\n    (build-api/compile-clj {:basis     project-basis\n                            :class-dir class-directory\n                            :src-dirs  [\"src\"]})\n\n    (build-api/uber {:basis     project-basis\n                     :class-dir class-directory\n                     :main      main-namespace\n                     :uber-file uberjar-file})))\n\n;; End of Build tasks\n;; ---------------------------------------------------------\n</code></pre> <p>Define Clojure functions to run the required build tasks</p> <ul> <li><code>clean</code> to remove build artefacts, e.g. <code>target</code> directory</li> <li><code>jar</code> creates a Jar file for a Clojure library, ready for publishing</li> <li><code>install</code> a built jar into the local Maven repository, e.g. `~/.m2/repository/</li> <li><code>publish</code> a built jar to Clojars.org </li> </ul> <p>Clojure Library build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build tasks\n\n(defn clean\n  \"Remove a directory\n  - `:path '\\\"directory-name\\\"'` for a specific directory\n  - `nil` (or no command line arguments) to delete `target` directory\n  `target` is the default directory for build artefacts\n  Checks that `.` and `/` directories are not deleted\"\n  [directory]\n  (when (not (contains? #{\".\" \"/\"} directory))\n    (build-api/delete {:path (or (:path directory) \"target\")})))\n\n(defn jar \"Run the CI pipeline of tests (and build the JAR).\"\n  [config]\n  (clean \"target\")\n  (let [config (project-config config)\n        class-directory (config :class-directory)]\n    (println \"\\nWriting pom.xml...\")\n    (build-api/write-pom (merge (pom-template config)))\n    (println \"\\nCopying source...\")\n    (build-api/copy-dir {:src-directory [\"resources\" \"src\"] :target-directory class-directory})\n    (println \"\\nBuilding JAR...\" (:jar-file config))\n    (build-api/jar config))\n  config)\n\n(defn install\n  \"Install a built JAR in the local Maven repository, e.g. `.m2/repository`\"\n  [config]\n  (let [config (project-config config)]\n    (build-api/install config))\n  config)\n\n(defn publish \n  \"Publish the built JAR to Clojars.\" \n  [config]\n  (let [{:keys [jar-file] :as config} (project-config config)]\n    (deploy-api/deploy\n     {:installer :remote :artifact (build-api/resolve-path jar-file)\n      :pom-file (build-api/pom-path (select-keys config [:library-name :class-directory]))}))\n  config)\n\n;; End of Build tasks\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#resources","title":"Resources","text":"<p> Clojure.org tools.build Guide</p> <p> Clojure.org tools.build API Docs</p> <p> Clojure.org tools.build release information</p>"},{"location":"clojure-cli/projects/templates/","title":"Creating projects from templates","text":"<p>Creating projects using a template is a quick way to get started or create a common .  A template will create the project structure, add libraries and even include example code.</p> <p>deps-new provides Clojure CLI specific templates and  Practicalli Project Templates provides production level templates with a REPL Reloaded workflow</p> deps-new built-in templates <p>The deps-new built-in templates for creating a project - <code>app</code> - simple project for a running application (uberjar) - <code>lib</code> - simple project for a library (jar) - <code>scratch</code> - a <code>deps.edn</code> file and <code>src/scratch.clj</code> - <code>template</code> - project for defining a custom template</p> Practicalli Project Templates <p> Practicalli Project Templates provide production level templates that include Practicalli REPL Reloaded Workflow tools, Docker &amp; Compose configurations, Makefile tasks for a consistent command line UI and GitHub workflows to manage quality of code and configuration.</p> <ul> <li><code>practicalli/minimal</code> - essential tools, libraries and example code</li> <li><code>practicalli/application</code> - general Clojure production level project template </li> <li><code>practicalli/service</code> - production level web services template with component management, Http-kit, Reitit and Swagger</li> <li><code>pracicalli/landing-page</code> - simple clojurescript website with bulma.io CSS and Figheel-main build tool. </li> </ul> clj-new provides Leiningen format templates <p>The Practicalli <code>:project/new</code> alias provides the seancorfield/clj-new tool which can use a wide range of templates (although some may only create Leinginen projects).  This project has been archived and deps-new is the recommended approach.</p> <p>Migrate to a Clojure CLI project if the template does not include a <code>deps.edn</code> file</p> <p> Clojure Projects with the REPL video demonstrates shows how to use clj-new</p> <p><code>clj-new</code> can create projects from <code>deps.edn</code> and Leiningen templates. A wide range of templates have been created by the Clojure community which can be found by searching on Clojars.org:</p> <ul> <li>clj-templates website - leiningen and boot templates</li> <li>deps.edn projects</li> <li>Leiningen projects</li> </ul>"},{"location":"clojure-cli/projects/templates/#add-deps-new","title":"Add deps-new","text":"<p>Add deps-new via a Clojure CLI user alias or  install as a tool.</p>  Practicalli Clojure CLI ConfigAlias Definitions <p><code>:project/create</code> alias provided by  Practicalli Clojure CLI Config runs the  seancorfield/deps-new tool to create Clojure CLI specific projects. </p> <p><code>:project/create</code> alias includes the  Practicall Project templates , extending the range of available templates</p> <p>Create the following alias definitions in the Clojure CLI user configuration, e.g. <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code> Clojure CLI user deps.edn configuration - :aliases {}<pre><code>:project/create\n{:replace-deps {io.github.seancorfield/deps-new\n                {:git/tag \"v0.5.2\" :git/sha \"253f32a\"}\n                io.github.practicalli/project-templates\n                {:git/tag \"2023-08-02\" :git/sha \"eaa11fa\"}}\n :exec-fn      org.corfield.new/create\n :exec-args    {:template practicalli/minimal\n                :name practicalli/playground}}\n</code></pre></p>"},{"location":"clojure-cli/projects/templates/#create-a-project","title":"Create a project","text":"<p>Open a terminal window and change to a suitable folder and create a project.  </p> <p>Create a project using the <code>:project/create</code> alias.</p> <p>The <code>practicalli/minimal</code> template and <code>practicalli/playground</code> name are used if <code>:template</code> and <code>:name</code> arguments are not specified.</p> <pre><code>clojure -T:project/create\n</code></pre> <p>The <code>-T</code> execution option runs the tool with Clojure.exec which uses keywords to specify the options for creating the project.</p> <p>Use the form <code>domain/app-or-lib-name</code> to specify a project name, typically with a company name or Git Service account name as the <code>domain</code>.</p> <p><code>:template</code> can be one of the deps-new built-in templates (<code>app</code>, <code>lib</code>) or one of the  Practicalli Project Templates.</p> <p>Create a project using the <code>practicalli/application</code> template and random-function name. </p> <pre><code>clojure -T:project/create :template practicalli/application :name practicalli/random-function\n</code></pre>"},{"location":"clojure-cli/projects/templates/#run-project-in-a-repl","title":"Run Project in a REPL","text":"<p>Change into the directory and test the project runs by starting a REPL with Terminal REPL</p> <pre><code>cd playground &amp;&amp; clojure -M:repl/rebel\n</code></pre> <p>A repl prompt should appear.</p> <p>Type code expressions at the repl prompt and press RETURN to evaluate them.</p> <pre><code>(+ 1 2 3 4 5)\n</code></pre> Try the project with your preferred editor <p>Using a Clojure aware editor, open the playground project and run the REPL.  Then write code expressions in the editor and evaluate them to see the result instantly.</p>"},{"location":"clojure-cli/projects/templates/#running-the-project","title":"Running the project","text":"<p>Run project with or without an alias:</p> <pre><code>clojure -M:alias -m domain.app-name\nclojure -M -m domain.app-name\n</code></pre> <p>In the project <code>deps.edn</code> file it can be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.</p> <pre><code>:project/run\n{:ns-default domain.main-namespace\n :exec-fn -main\n :exec-args {:port 8888}}\n</code></pre> <p>Then the project can be run using <code>clojure -X:project/run</code> and arguments can optionally be included in this command line, to complement or replace any default arguments in <code>exec-args</code>.</p>"},{"location":"clojure-cli/projects/templates/design-templates/","title":"Design templates","text":"<p>Create a custom template project for yourself, your team / organisation or an open source project</p> <p>Either copy one of the Practicalli Project Templates or create a base template project</p> <pre><code>clojure -T:project/create :template template :name domain/template-name\n</code></pre> Local only template <p>If a template is only used by yourself locally, then all that is needed is a <code>deps.edn</code> config with deps-new, <code>resources/domain/template-name/</code> directory containing a <code>template.edn</code> and files to make up the new project and optionally a <code>src/domain/template-name.clj</code> for programmatic transform</p>"},{"location":"clojure-cli/projects/templates/design-templates/#add-project-files","title":"Add project files","text":"<p><code>resources/domain/project_name/</code> directory contains files that are used to create a new project when using the template.</p> <p><code>resources/domain/project_name/template.edn</code> defines the declarative copy rules that manage where files are copied too, allowing for renaming of files and directories.</p>"},{"location":"clojure-cli/projects/templates/design-templates/#deps-new-template-project","title":"deps-new template project","text":"<p>deps-new specification defined with clojure.spec</p> <pre><code>(s/def ::root string?)\n(s/def ::description string?)\n(s/def ::data-fn symbol?)\n(s/def ::template-fn symbol?)\n(s/def ::files (s/map-of string? string?))\n(s/def ::open-close (s/tuple string? string?))\n(s/def ::opts #{:only :raw})\n(s/def ::dir-spec (s/cat :src string?\n                         :target (s/? string?)\n                         :files (s/? ::files)\n                         :delims (s/? ::open-close)\n                         :opts (s/* ::opts)))\n(s/def ::transform (s/coll-of ::dir-spec :min-count 1))\n(s/def ::template (s/keys :opt-un [::data-fn ::description ::root ::template-fn ::transform]))\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#use-template-locally","title":"Use template locally","text":"<p>Create projects from the new template locally by defining a Clojure CLI user alias using :local/root that points to the root directory of the template project.</p> <pre><code>  :project/create-local\n  {:replace-deps {io.github.seancorfield/deps-new\n                  {:git/tag \"v0.5.2\" :git/sha \"253f32a\"}\n                  practicalli/project-templates\n                  {:local/root \"/home/practicalli/projects/practicalli/project-templates/\"}}\n   :exec-fn      org.corfield.new/create\n   :exec-args    {:template practicalli/minimal\n                  :name practicalli/playground}}\n</code></pre> <p>Create a new project with the <code>project/create-local</code> alias</p> <pre><code>clojure -T:project/create-local :template domain/template-name\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#unit-tests","title":"Unit tests","text":"<p>Each template should have a unit test that checks against the deps-new template specification (written in clojure.spec)</p> <p>Once the unit test pass, create a new project from the template just created</p> <p>Checks should be made of the following aspects of a new project created with the new template.</p> <ul> <li>check library dependency versions</li> <li>run main and exec functions</li> <li>run test runner</li> <li>test buld task clean and jar | uberjar</li> </ul> <p>template.edn contains a declarative configuration of the project a template will generate</p> <p><code>src/domain/template-name.clj</code></p> <p><code>test/domain/template_name_test.clj</code> defines a unit test with <code>clojure.test</code> and <code>clojure.spec</code> which test the <code>practicalli/template/service/template.edn</code> configuration.</p>"},{"location":"clojure-cli/projects/templates/design-templates/#template-specification","title":"Template specification","text":"<p>The template configuration is tested against the <code>org.corfield.new/template</code> specification</p> <p>Specification defined with clojure.spec</p> <pre><code>(s/def ::root string?)\n(s/def ::description string?)\n(s/def ::data-fn symbol?)\n(s/def ::template-fn symbol?)\n(s/def ::files (s/map-of string? string?))\n(s/def ::open-close (s/tuple string? string?))\n(s/def ::opts #{:only :raw})\n(s/def ::dir-spec (s/cat :src string?\n                         :target (s/? string?)\n                         :files (s/? ::files)\n                         :delims (s/? ::open-close)\n                         :opts (s/* ::opts)))\n(s/def ::transform (s/coll-of ::dir-spec :min-count 1))\n(s/def ::template (s/keys :opt-un [::data-fn ::description ::root ::template-fn ::transform]))\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#publish-template","title":"Publish template","text":"<p>Templates are a shared Git repository, so push the template project to GitHub</p> <p>Include the shared repository within an alias definition within the Clojure CLI user deps.edn configuration, e.g. Practicalli Clojure CLI Config.</p> <p>Create a new project with the template using the alias.</p> <pre><code>clojure -T:project/create :template domain/template-name :name domain/project-name\n</code></pre> <p>:project/crate includes Practicalli Project Templates</p> <p>Practicalli Clojure CLI Config has been updated to include the practicalli/project-templates dependency, making available all the Practicalli templates.</p> <p>Default values for template.edn keys can also be defined in the <code>:exec-args {}</code> of an alias for the project template <pre><code>  :exec-args {:template practicalli/service\n              :name practicalli.gameboard/service}\n</code></pre></p>"},{"location":"clojure-cli/projects/templates/practicalli/","title":"Practicalli Project Templates","text":"<p>Practicalli Project templates provides tools for a REPL Reloaded Workflow and several production grade project configurations. </p> <p><code>:project/create</code> alias defined in  Practicalli Clojure CLI Config provides` provides seancorfield/deps-new tool for creating projects, including the  Practicalli Project Templates</p> <pre><code>clojure -T:project/create \n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/#available-templates","title":"Available Templates","text":"<p>Use the <code>:template</code> command line argument to specify a project template to generate the new Clojure project.</p> <ul> <li><code>practicalli/minimal</code> - essential tools, libraries and example code</li> <li><code>practicalli/application</code> - general Clojure production level project template </li> <li><code>practicalli/service</code> - production level web services template with Http-kit, Reitit and Swagger. Optional <code>: component</code> management with <code>:donut</code> or <code>:integrant</code></li> <li><code>pracicalli/landing-page</code> - simple clojurescript website with bulma.io CSS and Figheel-main build tool. </li> </ul> <p>Create service project with      Donut System components</p> <pre><code>clojure -T:project/create :template practicalli/service :name practicalli/todo-list :component :donut\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/#common-template-design","title":"Common Template Design","text":"<p> practicalli/project-templates provide production level templates that include Practicalli tools, Docker &amp; Compose configurations, Makefile tasks for a consistent command line UI and GitHub workflows to manage quality of code and configuration.</p>"},{"location":"clojure-cli/projects/templates/practicalli/#custom-user-namespace","title":"Custom user namespace","text":"<p>Practicalli <code>dev/user.clj</code> adds tools to the REPL on start up</p> <ul> <li><code>mulog_events.clj</code> custom publisher sends log events to portal</li> <li><code>portal.clj</code> launch portal data inspector and set log global context</li> <li><code>system_repl.clj</code> Component services e.g. donut-party/system, integrant REPL</li> <li><code>user.clj</code> provides help for custom user namespace, loads portal, mulog and tools.namespace.repl to support reloading Clojure code</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/#make-tasks","title":"Make tasks","text":"<p><code>Makefile</code> defines targets used across Practicalli projects, following the  make standard targets for users</p> <ul> <li><code>all</code>  calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean</li> <li><code>deps</code> download library dependencies (depend on <code>deps.edn</code> file)</li> <li><code>dist</code> create a distribution tar file for this program or zip deployment package for AWS Lambda</li> <li><code>lint</code> run lint tools to check code quality  - e.g MegaLinter which provides a wide range of tools</li> <li><code>format-check</code> report format and style issues for a specific programming language</li> <li><code>format-fix</code> update source code files if there are format and style issues for a specific programming language</li> <li><code>pre-commit</code> run unit tests and code quality targets before considering a Git commit</li> <li><code>repl</code> run an interactive run-time environment for the programming language</li> <li><code>test-unit</code> run all unit tests</li> <li><code>test-ci</code> test running in CI build (optionally focus on integration testing)</li> <li><code>clean</code> remove files created by any of the commands from other targets (i.e. ensure a clean build each time)</li> </ul> <p>Practicalli Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.</p> <ul> <li><code>docker-build</code> build Clojure project and run with docker compose</li> <li><code>docker-build-clean</code> build Clojure project and run with docker compose, removing orphans</li> <li><code>docker-down</code> shut down containers in docker compose</li> <li><code>swagger-editor</code> start Swagger Editor in Docker</li> <li><code>swagger-editor-down</code> stop Swagger Editor in Docker</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/#docker","title":"Docker","text":"<p>Docker configuration builds and runs the Clojure project in a Docker container, orchestrating with other services including a Database.</p> <p>The service and application project templates include the following files</p> <ul> <li><code>Dockerfile</code> multi-stage build and run, with JVM optomisations for a Docker container </li> <li><code>.dockerignore</code> patterns to opomise copying of files to the docker build image</li> <li><code>compose.yaml</code> configuration for orchestrating additional services, e.g. postgresql database</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/application/","title":"Practicalli Application template","text":"<p>Create a general Clojure application with REPL Reloaded workflow.</p>"},{"location":"clojure-cli/projects/templates/practicalli/application/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.</p> <p>Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/","title":"Practicalli Landing Page","text":"<p>Build simple websites and landing pages using ClojureScript and figwheel-main.</p> <pre><code>clojure -T:project/create :template landing-page :name practicalli/website-name\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/#template-design","title":"Template design","text":"<p>Configuration files</p> <ul> <li><code>deps.edn</code> project dependencies and aliases defining figwheel builds</li> <li><code>dev.cljs.edn</code> development build configuration</li> <li><code>live.cljs.edn</code> live build configuration (GitHub pages deployment by default)</li> <li><code>figwheel-main.edn</code> general figwheel configuration</li> </ul> <p>Clojure code</p> <ul> <li><code>src/project/landing-page.clj</code> compose components to render the website</li> <li><code>src/project/components.clj</code> functions that define component and associated helper functions</li> <li><code>src/project/data.clj</code> data structure passed in part or whole to each component, via the <code>landing-page</code>.</li> </ul> <p><code>project.data</code> namespace defines an example data structure as a static value (def).  Use an atom to contain the data structure if the data should be updated by components in the project.</p>"},{"location":"clojure-cli/projects/templates/practicalli/minimal/","title":"Practicalli Minimal Project Template","text":"<p>A Clojure project with minimal dependencies and example code, useful for experimenting or building a new project from a minimal setup.</p>"},{"location":"clojure-cli/projects/templates/practicalli/minimal/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.</p> <p>Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/service/","title":"Practicalli Service template","text":"<p>Develop web services and APIs using the <code>practicalli/service</code> template.</p> <pre><code>clojure -T:project/create :template practicalli/service\n</code></pre> <p>The <code>practicalli/services</code> includes:</p> <ul> <li>http-kit provides an HTTP web server responding to HTTP requests</li> <li>reitit routing</li> <li>mulog event logging and publisher</li> <li>Portal data inspector</li> <li>Makefile with common Practicalli tasks</li> </ul> <p>A component system can be included by providing the <code>:component :donut</code> or <code>:component integrant</code> command line arguments.</p>"},{"location":"clojure-cli/projects/templates/practicalli/service/#component-systems","title":"Component systems","text":"<p>Components in the system can be managed during development by evaluating functions in the REPL.</p> <ul> <li><code>(start)</code> starts all components in order</li> <li><code>(stop)</code> stops  all components in order</li> <li><code>(restart)</code> reload changed namespaces and restart all components in order</li> <li><code>(system)</code> prints out the system configuration</li> </ul> <p>The <code>system-repl.clj</code> defines the functions to manage components, using the chosen component library, e.g. Donut system, Integrant REPL.</p> <p>When running the application from the command line, the <code>src/domain/project/service/-main</code> function calls the initialisation of components and creates a var called <code>running-system</code> that contains the initialised system components.  <code>-main</code> contains a shutdown hook that responds to SIGTERM signals, triggering a shutdown of components in the <code>running-system</code>.</p> Donut SystemIntegrant <p>Include Donut system configuration and REPL functions</p> <pre><code>clojure -T:project/create :template practicalli/service :component :donut\n</code></pre> <ul> <li><code>src/domain/project/system.clj</code> defines the system components</li> <li><code>dev/system-repl.clj</code> defines funtions to manage the system components</li> </ul> <p>Each component is defined within the <code>system</code> namespace in the <code>domain.project.system/main</code> hash-map.  Each component definition has a start and stop function, optionally passing configuration options and environment variables for that component.</p> <p>Include Integrant system configuration and Integrant REPL functions to support development</p> <pre><code>clojure -T:project/create :template practicalli/service :component :integrant\n</code></pre> <ul> <li><code>src/domain/project/system.clj</code> defines the system components</li> <li><code>dev/system-repl.clj</code> defines funtions to manage the system components</li> </ul> <p>Each component is started with an init multi-method with a the specific component name (keyword).  Each <code>init</code> multi-method provides the specific Clojure code to start the component.</p> <p>A <code>halt</code> multi-method is provided for each component that requires shutting down, e.g. http server, database pool, logging publisher, etc.</p> <p>During development and testing, the components are managed from the <code>user</code> namespace by evaluating the <code>(start)</code>, (stop) or <code>(restart)</code> functions.</p>"},{"location":"clojure-cli/projects/templates/practicalli/service/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.  Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/repl/","title":"Clojure REPL","text":"<p>The REPL is the environment in which all Clojure code runs, whether that be during development, testing or in production systems.</p> <p>A Terminal REPL provides a simple way to interact with the REPL, sending code expressions for evaluation and returning results. </p> <p>Use a  terminal REPL for </p> <ul> <li>quick experiments</li> <li>long running processes (e.g. http severs running Clojure) </li> <li>interact with the REPL state and manage components (e.g restarting system components, querying UI component state or services system state).</li> <li>a REPL process separate from a specific editor control</li> </ul> <p>REPL connected Editor</p> <p>A Clojure aware editor connected to the REPL is used for the majority of Clojure development.  One or more expressions from a source code file can be sent to the REPL for evaluation, displaying the results inline.</p>"},{"location":"clojure-cli/repl/#rebel-terminal-repl-ui","title":"Rebel Terminal REPL UI","text":"<p>Rebel is a REPL terminal UI that provides auto-completion, function call syntax help and documentation, themes and key binding styles to enhance the development experience.  Clojure tools also include a REPL with a minimal interface by default.</p> <p> </p>"},{"location":"clojure-cli/repl/#install-rebel","title":"Install Rebel","text":"Practicalli Clojure CLI ConfigDefine Rebel AliasClojure CLI REPL <p><code>:repl/rebel</code> alias is provided by  Practicalli Clojure CLI Config to run rebel readline.</p> <p><code>:repl/reloaded</code> alias runs Rebel with tools to support the  Practicalli REPL Reloaded, providing a custom REPL startup with support for Portal data inspector and Mulog event logs.</p> <p>Both aliases will start an nREPL server for  Clojure aware editors to connect.</p> <p>Rebel libraries are downloaded the first time the Rebel alias is used.</p> <p>Add an alias called <code>:repl/rebel</code>to the user <code>deps.edn</code> configuration, e.g. <code>~/.config/clojure/deps.edn</code></p> <p>Basic Rebel terminal UI alias</p> ~/.config/clojure/deps.edn<pre><code>:repl/rebel \n{:extra-deps {com.bhauman/rebel-readline {:mvn/version \"0.1.5\"}}\n :main-opts  [\"-m\" \"rebel-readline.main\"]}\n</code></pre> <p>Rebel terminal UI alias with nREPL for editor connection</p> ~/.config/clojure/deps.edn<pre><code>:repl/rebel\n{:extra-deps {nrepl/nrepl                {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl          {:mvn/version \"0.31.0\"}\n              com.bhauman/rebel-readline {:mvn/version \"0.1.4\"}}\n :main-opts  [\"-e\" \"(apply require clojure.main/repl-requires)\"\n              \"--main\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n</code></pre> <p> Practicalli Clojure CLI Config contains aliases for a basic terminal UI and a headless (non-interactive) terminal UI, each starting an nREPL server for editor connection.</p> <p>Alias definitions for a basic terminal UI REPL</p> <p>Interactive client REPL with nREPL server for Clojure Editor support <pre><code>:repl/basic\n{:extra-deps {nrepl/nrepl {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl {:mvn/version \"0.28.7\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"]}\n</code></pre></p> <p>Headless REPL with nREPL server for Clojure Editor support <pre><code>:repl/headless\n{:extra-deps {nrepl/nrepl {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl {:mvn/version \"0.28.7\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"]}\n</code></pre></p> <p>To have a basic terminal UI REPL prompt use the <code>:repl/basic</code> alias to start a REPL process with nREPL connection.</p> <pre><code>clj -M:repl/basic\n</code></pre> <p>To only have the REPL process without a REPL prompt, use the <code>:repl/headless</code> aliase to start a REPL process with nREPL connection.  This approach is useful to separate the REPL output from the editor whilst keeping all the interaction with the REPL via the editor.</p> <pre><code>clj -M:repl/headless\n</code></pre> Terminal REPL and Editor <p>Including an nREPL server when starting the REPL allows clojure ware editors to connect to the REPL process, providing a more effective way to write and extend Clojure code.</p> <p>An external REPL can still be of use even when only evaluating code in a Clojure editor. Separating the REPL process from the editor process allows the editor to be closed, upgraded or swapped for a different editor without having to end the REPL session.  Different editors could be connected to the same REPL to use particular features they provide.</p> <p>A REPL process can be long running, staying alive for days, weeks or months when working on larger projects.  Avoiding stop and start of the REPL maintains state in the REPL, maintaining the flow of the Clojure workflow.</p>"},{"location":"clojure-cli/repl/#customize-rebel-readline","title":"Customize Rebel Readline","text":"<p><code>:repl/help</code> in the repl prompt shows the Rebel configuration options</p> <p>Set configuration options in a <code>rebel_readline.edn</code> file, in <code>$XDG_CONFIG_HOME/clojure/</code> or <code>$HOME/.clojure</code></p> Practicalli Rebel Readline Configuration options $XDG_CONFIG_HOME/clojure/rebel_readline.edn<pre><code>;; ---------------------------------------------------------\n;; Rebel Readline Configuration\n;;\n;; Customise use and appearance\n;; ---------------------------------------------------------\n\n{;; Vi or Emacs style key-map\n ;; :viins or :emacs. Default :emacs\n :key-map     :viins\n\n ;; Color theme - light or dark\n ;; :color-theme :light-screen-theme\n :color-theme :dark-screen-theme\n\n ;; Enable syntax highlight. Default true}\n :hihighlight true\n\n ;; Enable complete on tab. Default true}\n :completion  true\n\n ;; Enable function documentation Default true\n :eldoc  true\n ;; auto indent code on newline. Default true}\n :indent true\n\n ;; rebind root *out* during read to protect linereader, Default true}\n :redirect-output true\n\n ;; Custom key-bindings applied after all other \n :key-bindings {}}\n</code></pre>"},{"location":"clojure-cli/repl/#next-steps","title":"Next Steps","text":"<p> Code In The REPL </p> <p> Managing Libraries In The REPL </p> <p> Help In The REPL </p> <p> Custom REPL Startup </p> <p> REPL Uncovered </p>"},{"location":"clojure-cli/repl/coding/","title":"Coding in the REPL","text":"<p>Clojure code can be typed into the REPL directly and the result instantly returned.  Code can also be loaded from a project source code files, to run pre-written code.</p> Clojure Editors are the main tool for writing code <p>An editor connected to a Clojure REPL and evaluating from source code files is the most effective way for writing Clojure code.  </p> <p>Evaluating code in an editor automatically uses the correct namespace, avoiding the need to change namespaces or fully qualify function calls. Evaluation results can be shown in-line, as comments next to the code or in a data inspector.  </p> <p>Editors provide structural editing and Clojure syntax checking, along with general editor features. and </p>"},{"location":"clojure-cli/repl/coding/#using-the-repl","title":"Using the REPL","text":"<p>Use the <code>clojure</code> command to start a REPL with Rebel, or the <code>clj</code> wrapper with the Clojure CLI REPL (requires <code>rlwrap</code> binary).</p> Rebel REPLClojure CLI REPL <p>Start a Clojure REPL with Rebel terminal UI which also starts an nREPL server which a Clojure editor can connect too.</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>A REPL prompt displays ready to evaluate a Clojure expression.</p> <p> </p> <p>Start a Clojure REPL with a basic UI which also starts an nREPL server which a Clojure editor can connect too.</p> <pre><code>clj -M:repl/basic\n</code></pre> <p>The <code>clj</code> wrapper requires <code>rlwrap</code> binary.</p> <p>A REPL prompt displays ready to evaluate a Clojure expression.</p> Project dependencies automatically downloaded on REPL start <p>When a REPL is started from the root of a Clojure project the project dependencies are automatically downloaded (unless previously downloaded to the local maven cache, <code>.m2/</code>) and project specific paths are added, e.g. <code>src</code> tree.</p> Use REPL with a Clojure project <p>A REPL can run without a Clojure project, however, libraries and code are simpler to manage within project source and configuration files.</p>"},{"location":"clojure-cli/repl/coding/#repl-start-state","title":"REPL start state","text":"<p>The Clojure REPL always starts in the <code>user</code> namespace.</p> <p>During startup the the <code>clojure.core</code> functions are required (made available) in the user namespace, so <code>(map inc [1 2 3])</code> can be called without specifying the <code>clojure.core</code> namespace in which those functions are defined.</p> <p>If clojure.core were not required, then the expression would be <code>(clojure.core/map clojure.core/inc [1 2 3])</code></p>"},{"location":"clojure-cli/repl/coding/#evaluating-code","title":"Evaluating code","text":"<p>Type Clojure code at the <code>=&gt; user</code> REPL prompt</p> <p>Press <code>Enter</code> to evaluate the code and see the result.</p> <p> </p> <p>Up and Down navigate the REPL history, providing an efficient way to evaluate the same code many times.</p> <p>In Rebel, typing part of function name shows matches available, Tab to cycle through the choices, Enter to select.</p> <p> </p>"},{"location":"clojure-cli/repl/coding/#load-code-from-file","title":"Load code from file","text":"<p>Clojure code is usually saved in files and each file has a namespace definition that matches the file path, using the <code>ns</code> function. The file <code>src/practicalli/playground.clj</code> has the namespace <code>practicalli.playground</code></p> <pre><code>(ns practicalli.playground)\n</code></pre> <p>Requiring the namespace of a file will evaluate (load) the code from that file in the REPL.</p> <pre><code>(require 'practicalli.playground)\n</code></pre> <p>Functions defined in that namespace can be called using their fully qualified names.  e.g. if the namespace contains a function called <code>main</code>, that function can be called using <code>(practicalli.playground/main)</code>.</p> Change namespaces <p>Change the namespace to <code>practicalli.playground</code> to call functions defined in that namespace by their unqualified function name, eg. <code>(main)</code>, rather than the fully qualified name, e.g. <code>(practicalli.playground/main)</code></p> <p><code>in-ns</code> will change change the current namespace to the one specified as an argument.</p> <pre><code>(in-ns 'practicalli.playground)\n</code></pre> <p>Now the <code>(main)</code> function can be called without having to include the full namespace name.</p> <p>Typically it is more efficient to stay in the <code>user</code> namespace and require all other namespaces required.</p>"},{"location":"clojure-cli/repl/coding/#reload-code-changes","title":"Reload code changes","text":"<p>The <code>:reload</code> option to <code>require</code> will load in any changes to a namespace that happened outside of the REPL, eg. using an editor to change the source code in the file.</p> <pre><code>(require 'practicalli.playground :reload)\n</code></pre> <p>Use the <code>:verbose</code> option when issues occur loading a particular namespace.  As the namespace being required may also require other namespaces, multiple namespaces may be loaded from one <code>require</code> expression.</p> <p><code>:verbose</code> shows a full list of the namespaces being loaded.</p> <pre><code>(require 'practicalli.playground :reload :verbose)\n</code></pre> Reload in Terminal REPL for unconnected editor <p>When using an editor that is not connected to the Clojure REPL, then reloading is an effective way of updating the code with all the changes saved in the file.</p>"},{"location":"clojure-cli/repl/coding/#close-repl","title":"Close REPL","text":"<p><code>:repl/quit</code> at the REPL prompt will end the REPL session and all code not saved to a file will be lost.</p> <p>Ctrl+c if the repl process does not return to the shell prompt.</p>"},{"location":"clojure-cli/repl/coding/#next-steps","title":"Next steps","text":"<p>Managing Library dependencies in REPL</p>"},{"location":"clojure-cli/repl/help/","title":"Help at the REPL","text":"<p>rebel readline provides tools to help you discover and use functions from clojure.core and any other libraries you add to the REPL.</p> <p><code>:repl/help</code> will show all the commands available for rebel readline</p> <p>Tab to autocomplete the current characters into a function name.  All functions that match the characters will be show, allowing quick discovery of functions available. Typing in the first few characters of a function and press</p> <p> </p> <p>Moving the cursor after the name of a function will show the signatures available, so a function can be called with the correct number and form of arguments.</p> <p> </p> <p>Ctrl+C+Ctrl+d on a function name shows the docstring to help understand the functions purpose.</p> <p> </p> <p><code>clojure.repl/doc</code> function also shows the docstring of a function <code>(clojure.repl/doc doc)</code></p> <p>Ctrl+C+Ctrl+a on a name shows all the possible matching functions to help you discover what is available.  Tab through the list of matches, Enter to select a function</p> <p></p>"},{"location":"clojure-cli/repl/help/#rebel-commands","title":"Rebel Commands","text":"<p>Type <code>:repl/help</code> or <code>:repl</code> TAB to see a list of available commands.</p> Keybinding Description <code>:repl/help</code> Prints the documentation for all available commands. <code>:repl/key-bindings</code> search or list current key bindings <code>:repl/quit</code> Quits the REPL <code>:repl/set-color-theme</code> Change the color theme <code>:dark-screen-theme</code> <code>:light-screen-theme</code> <code>:repl/set-key-map</code> Change key bindings to given key-map, <code>:emacs</code> <code>:vicmd</code> <code>:viins</code> <code>:repl/toggle-color</code> Toggle ANSI text coloration on and off <code>:repl/toggle-completion</code> Toggle the completion functionality on and off <code>:repl/toggle-eldoc</code> Toggle the auto display of function signatures on and off <code>:repl/toggle-highlight</code> Toggle readline syntax highlighting on and off <code>:repl/toggle-indent</code> Toggle the automatic indenting of Clojure code on and off"},{"location":"clojure-cli/repl/help/#key-bindings","title":"Key-bindings","text":"Keybinding Description <code>Ctrl-C</code> aborts editing the current line <code>Ctrl-D</code> at the start of a line =&gt; sends an end of stream message <code>TAB</code> word completion or code indent when cursor in whitespace at the start of line <code>Ctrl-X_Ctrl-D</code> Show documentation for word at point <code>Ctrl-X_Ctrl-S</code> Show source for word at point <code>Ctrl-X_Ctrl-A</code> Show apropos for word at point <code>Ctrl-X_Ctrl-E</code> Inline eval for SEXP before the point <p>Examine key-bindings with the <code>:repl/key-bindings</code> command.</p>"},{"location":"clojure-cli/repl/libraries/","title":"Using Clojure libraries in the REPL","text":"<p>A library should be included as a dependency in order to use it within the REPL.</p> <p>Add library dependencies to the top level <code>:deps</code> key in a project <code>deps.edn</code> configuration file, or add via an alias if the library is use at development time.</p> <p>Aliases from a user configuration can also add optional libraries when running a REPL, e.g. Practicalli Clojure CLI config</p> <pre><code>{:paths [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure {:mvn/version \"1.10.3\"}}\n\n :aliases\n {\n  :database/h2\n  {:extra-deps {com.h2database/h2                 {:mvn/version \"2.1.210\"}\n                com.github.seancorfield/next.jdbc {:mvn/version \"1.2.772\"}}}\n #_()}\n</code></pre> Finding libraries <p>Search for community libraries via the Clojars.org website</p> <p><code>clojure -M:search/libraries pattern</code> where pattern is the name of the library to search for.  Copy the relevant results into the project <code>deps.edn</code> file.</p> <p><code>clojure -M:search/libraries --format:merge pattern</code> will automatically add the library into the <code>deps.edn</code> file.</p> <p><code>clojure -X:deps find-versions :lib fully.qualified/library-name :n 5</code> returns the last 5 versions of the given library.</p>"},{"location":"clojure-cli/repl/libraries/#include-library","title":"Include library","text":"<p>Open a terminal and change to the root of the Clojure project directory, where the <code>deps.edn</code> file can be found.</p> <p>Start the REPL including the <code>:database/h2</code> alias to include every library defined in the <code>:deps</code> key and libraries in the <code>:database/h2</code> alias.  This example is using rebel readline rich terminal UI</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>This command will include</p> <p>Add aliases to include optional libraries, such as those used for development.  In this example, the H2 database and next.jdbc libraries are included along with those libraries in the <code>:deps</code> key of <code>deps.edn</code></p> <pre><code>clojure -M:database/h2:repl/rebel\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#load-namespace","title":"Load namespace","text":"<p>At the REPL prompt, require a namespace from the project to load all the code from that namespace and any namespaces required.</p> <p>If a project was created with the command <code>clojure -T:project/new :template app :name practicalli/status-monitor</code> then the main namespace will be <code>practicalli.status-monitor</code></p> <pre><code>(require '[practicalli.status-monitor])\n</code></pre> <p>The <code>require</code> function loads all the code from the main namespace.  When an <code>ns</code> form is read, required namespaces in the <code>ns</code> form are also loaded.</p>"},{"location":"clojure-cli/repl/libraries/#reloading-namespace","title":"Reloading namespace","text":"<p>Clojure is a dynamic environment, so changes to function definitions (<code>defn</code>) and shared symbol names (<code>def</code>) can be updated without restarting the REPL.</p> <p><code>require</code> loads the code from the specified namespace.  Using the <code>:reload</code> option forces the namespace to be loaded again, even if it was already loaded.</p> <p>When changes are made to a namespace in the source code file, <code>:reload</code> ensures those changes become the code running in the REPL</p> <pre><code>(require '[practicalli.status-monitor] :reload)\n</code></pre> <p>If errors occur when loading or reloading the namespace with require, the <code>:verbose</code> option will show all the namespaces that are loaded.  This may show issues or help track down conflicting namespaces or functions.</p> <pre><code>(require '[practicalli.status-monitor] :reload :verbose)\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#hotload-libraries","title":"Hotload libraries","text":"Hotload Libraries in the REPL <p><code>add-libs</code> function from the <code>clojure.tools.deps.alpha</code> library is an experimental approach to hot-loading library dependencies without having to restart the REPL or add those dependencies to the project <code>deps.edn</code>.  This provides a simple way to try out libraries.</p> <p>hotload libraries secion for more details and how to use with Clojure editors.</p> <p>Start a REPL session using Clojure CLI with the <code>:lib/hotload alias</code>, including rebel readline for an enhance REPL terminal UI.</p> <pre><code>clojure -M:lib/hotload:repl/rebel\n</code></pre> <p></p> <p>Require the <code>clojure.tools.deps.alpha</code> library and refer the <code>add-libs</code> function.  The <code>add-libs</code> function can then be called without having to use an alias or the fully qualified name.</p> <pre><code>(require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n</code></pre> <p>Hotload a library into the REPL using the <code>add-lib</code> function in the following form, where <code>domain/library</code> is the fully qualified name of the library and <code>RELEASE</code> is a string of the version number of that library to use.</p> <pre><code>(add-libs '{domain/library {:mvn/version \"RELEASE\"}})\n</code></pre> <p>Multiple libraries can be hot-loaded in a single <code>add-libs</code> expression</p> <pre><code>(add-libs '{hhgttg/meaning {:mvn/version \"4.2.0\"}\n            eternity/room  {:mvn/version \"1.0.1\"}})\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#hotload-hiccup-in-a-terminal-repl","title":"Hotload hiccup in a terminal REPL","text":"<p>The hiccup library converts clojure structures into html, where vectors represent the scope of keywords that represent html tags.</p> <p>Load the hiccup library using add-libs</p> <pre><code>(add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n</code></pre> <p>Require the hiccup library so its functions are accessible from the current namespace in the REPL.</p> <pre><code>(require '[hiccup.core :as hiccup])\n</code></pre> <p>Enter an expression using the <code>hiccup/html</code> function to convert a clojure data structure to html.</p> <pre><code>(hiccup/html [:div {:class \"right-aligned\"}])\n</code></pre> <p>The hiccup expression returns a string of the html code.</p> <p></p>"},{"location":"clojure-cli/repl/repl-uncovered/","title":"Read, Evaluate Print Loop (REPL)","text":"<p>The REPL provides a fast, powerful and fun way to develop code and is the hard of the Clojure developers workflow.  The REPL allows you to quickly test out designs and your domain knowledge of the system you are building, easily accommodating multiple designs to help you evaluate the best approach.</p> <p>Starting a REPL is the first thing you do after creating or downloading a project.</p> <p>The REPL allows you to run any existing code, write new code and change code.  Each time you can see the results of your code instantly.</p> <p>The REPL can run all of your code or simply get the result of an individual expression.  You can inspect run-time values and continually develop your code without having to restart each time.</p> <p>Hint If you are not using the REPL for your Clojure development you are missing out on a highly productive workflow.  Once you start using a REPL as part of you development cycle you will feel lost without one.</p>"},{"location":"clojure-cli/repl/repl-uncovered/#how-the-repl-works-simple-version","title":"How the REPL works (simple version)","text":"<p>A Clojure REPL has 4 stages:</p> <ul> <li>Read - read in the code</li> <li>Evaluate - evaluate the code</li> <li>Print - show the results</li> <li>Loop - on to the next expression</li> </ul> <p>Its useful to understand the difference between Read and Evaluate, especially when you get as far as writing macro's for Clojure.</p>"},{"location":"clojure-cli/repl/repl-uncovered/#the-reader","title":"The Reader","text":"<p>The Reader parses the Clojure source code, form by form, producing the Clojure data structures an [Abstract Syntax Tree] (AST).</p> <p>Due to the syntax of Clojure, much of the source code is already in the right structure.  Any macros will be expanded into its Clojure structure.</p> <p>These data structures are then evaluated: Clojure traverses the data structures and performs actions like function application or var lookup based on the type of the data structure.</p> <p>For example, when Clojure reads the text (+ 1 2), the result is a list data structure whose first element is a + symbol, followed by the numbers 1 and 2. This data structure is passed to Clojure\u2019s evaluator, which looks up the function corresponding to + and applies that function to 1 and 2.</p> <p></p>"},{"location":"clojure-cli/repl/repl-uncovered/#the-reader_1","title":"The Reader","text":"<p>Hint Clojure is a homoiconic language, which is a fancy term describing the fact that Clojure programs are represented by Clojure data structures. This is a very important difference between Clojure and most other programming languages.  It means that Clojure is defined in terms of the evaluation of data structures and not in terms of the syntax of character streams/files.</p> <p>It is quite common, and easy, for Clojure programs to manipulate, transform and produce other Clojure programs.</p> <p>The reader has syntax defined in terms of characters, and the Clojure language has syntax defined in terms of symbols, lists, vectors, maps etc. The reader is represented by the function read, which reads the next form (not character) from a stream, and returns the object represented by that form.</p> <p>There are also Reader Macros that define special rules on top of the Clojure syntax.  They give the language some additional syntax sugar, making your Clojure code compact.  See the reference section on reader macros for more information</p>"},{"location":"clojure-cli/repl/repl-uncovered/#evaluator","title":"Evaluator","text":"<p>The Evaluator takes the data structure as an argument (from the Reader) and processes it using rules corresponding to the data structure\u2019s type, returning the result.</p> <p>To evaluate a symbol, Clojure looks up what the symbol refers to.</p> <p>To evaluate a list, Clojure looks at the first element of the list and calls a function, macro, or special form.</p> <p>Any other values including strings, numbers and keywords simply evaluate to themselves.</p> <p>Hint Read the section on Reading, Evaluation and Macros from BraveClojure to see examples of the REPL process.</p>"},{"location":"clojure-cli/repl/troubleshooting/","title":"Troubleshooting the REPL","text":"<p>The aspects to consider when a REPL process fails to run are:</p> <ul> <li>Some code expressions are not correct</li> <li>Dependencies are not available</li> <li>Project (or editor) misconfigured</li> </ul>"},{"location":"clojure-cli/repl/troubleshooting/#code-expression-failing","title":"Code expression failing","text":"<p>All code in the project must compile and be syntactically correct, even if that code is in a rich <code>(comment ,,,)</code> block.</p> <p>A Clojure expression following a Reader comment, <code>#_</code> does not have to compile, however it must be syntactically correct, i.e. balanced parentheses.</p> <p>Add a line comment, <code>;;</code>, to any code that is suspected of not compiling or being syntactically incorrect (or delete that code).</p>"},{"location":"clojure-cli/repl/troubleshooting/#editor-repl-fails-to-start","title":"Editor REPL fails to start","text":"<p>If using a jack-in approach with the editor to start the repl, run a terminal UI REPL with an nREPL server and try connecting to that REPL from the editor.</p> <p>Clojure CLI repl - rebel terminal UI</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Then require the main namespace and see if there are issues, optionally using :verbose to see which libraries are being loaded.</p> <pre><code>(require '[practicalli.service] :verbose)\n</code></pre> <p>If the REPL runs correctly, it is likely the editor configuration is missing something or is incorrect.  Check the configuration for running a Clojure project with the editor.</p>"},{"location":"clojure-cli/repl/troubleshooting/#terminal-ui-repl-fails-in-project","title":"Terminal UI REPL fails in project","text":"<p>If the REPL does not run correctly or the namespace fails to load, run a repl without any extra development dependencies (tooling, dev libraries, etc) and load the main namespace</p> <pre><code>clj\n</code></pre>"},{"location":"clojure-cli/repl/troubleshooting/#repl-doesnt-start-in-any-project","title":"REPL doesnt start in any project","text":"<p>Run the <code>clojure</code> command in a directory that is not part of any existing Clojure project.  This will run the REPL with only the <code>org.clojure/clojure</code> dependency</p> <p>Run <code>clojure -Sdescribe</code> to check that the Clojure CLI is using the correct configuration files and is the expected version.</p> <p>If a REPL prompt appears, then Clojure CLI is working.  If a REPL prompt does not appear, then reinstall the Clojure CLI or upgrade to a newer version.</p> <p>Clojure CLI install - Practicalli Guide</p>"},{"location":"clojure-cli/repl/troubleshooting/#repl-starts-but-requiring-code-fails","title":"REPL starts but requiring code fails","text":"<p>Creating a new project is a fast way to check development tooling is working correctly.  A project can be created with <code>clojure -T:project/create</code> (with  Practicalli Clojure CLI Config installed)</p> <p>If a REPL process starts correctly for a new project but not the existing project, then its most likely one or more expressions in the existing project that are causing an error or the project <code>deps.edn</code> configuration.</p> <p>Copy the <code>deps.edn</code> configuration from the existing project to the root of the new project (or just the <code>:deps</code> section of the <code>deps.edn</code> configuration).  Run the REPL again using the <code>clojure</code> command.  If the REPL fails then it is likely an issue with the exiting projects <code>deps.edn</code> file or one of the dependencies</p>"},{"location":"clojure-cli/repl/troubleshooting/#dependency-issues","title":"Dependency issues","text":"<p>Projects typically depend on many other libraries and sometimes those libraries depend on other libraries too.</p> <p>When running the <code>clojure</code> command to run a terminal UI REPL, libraries are retrieved from remote repositories (Maven Central, Clojars.org) and stored in a local cache <code>~/.m2/repositories</code></p> <p>If a dependency is not available then a warning should state which library cannot be downloaded and from which repository</p> <p>Check the extent of the dependencies for the existing project:</p> <pre><code>clojure -Stree\n</code></pre> <p>Use the antq tool to check for a newer version of a dependency</p> <pre><code>clojure -T:project/outdated\n</code></pre> <p>If libraries are likely to become unavailable (i.e. old versions) then consider creating a local repository service with Artefactory or Nexus, which can share library depenencies between development teams of an organisation.</p>"},{"location":"clojure-editors/","title":"Editors for Clojure development","text":"<p>The best editor to use for learning Clojure is the editor already familiar with (or want to learn).</p> <p>Use SublimeText &amp; ClojureSublimed if unsure where to start as it will be the simplest tool to use.</p>"},{"location":"clojure-editors/#clojure-editor-features","title":"Clojure editor features","text":"<p>An ideal Clojure editor includes the these core features</p> <ul> <li>running / connecting to a REPL process</li> <li>evaluation results inline or in a repl window (fast feedback on what the code does)</li> <li>syntax highlighting (including highlight of matching parens)</li> <li>structural editing to ensure parens are balanced when writing and refactor code</li> <li>data inspector to visualise large and nested data, or connection to  data inpector tools</li> </ul> <p></p>"},{"location":"clojure-editors/#clojure-aware-editors","title":"Clojure aware editors","text":"<p>Emacs (Spacemacs, Doom, Prelude), Neovim (Conjure) and VSCode (Calva) are the most common open source Editors for Clojure and ClojureScript development.</p> <p>SublimeText and IntelliJ are commercial editors (with limited free editions) which also provide Clojure support</p> EmacsNeovimVSCodeSublimeTextPulsar (Atom)Intellij <p></p> <p>Emacs is a very powerful editor with thousands of packages enabling a person to do almost any digital task concievable.  Emacs is highly extensible via the ELisp programming language used to write configuration and the numerous Emacs packages. Native Compilation of Emacs packages dramatically speeds up many common tasks.</p> <p>Emacs uses CIDER and Clojure LSP for a feature rich clojure development experience.</p> <p>Use one of the popular community configurations for Emacs or visit the  CIDER documentation to learn how to add Clojure support to Emacs.</p> SpacemacsPrelude EmacsDoom EmacsVanilla Emacs &amp; Cider <p></p> <p> Spacemacs is a community configuration bringing  Emacs features and  Vim style editing together.  Spacemacs uses a mnemonic menu system that makes it easy to learn and provides detailed documentation for configuring and using Emacs.</p> <p> Practicalli Spacemacs provides a guide to Clojure development, vim-style editing, documenting with org-mode, Git version control with Magit, Issues &amp; Pull Requests with Forge and dozens of other features.</p> <p> Practicalli Spacemacs Config contains a customised configuration for Clojure development and supporting tools.</p> Free Desktop XDG ConfigClassic Config <pre><code>git clone https://github.com/practicalli/spacemacs.d.git $XDG_CONFIG_HOME/spacemacs`\n</code></pre> <pre><code>git clone https://github.com/practicalli/spacemacs.d.git $HOME/.spacemacs.d`\n</code></pre> <p>The Practicalli configuration should replace the <code>~/.spacemacs</code> file if it exists</p> <p>Spacemacs install guide - Practicalli Spacemacs</p> <p><p> </p></p> <p> Emacs Prelude is an easy to use Emacs configuration for Emacs newcomers and lots of additional power for Emacs power users, from the author of CIDER - the definitive Clojure IDE for Emacs.</p> <p>Prelude uses the traditional chorded key bindings to drive Emacs, e.g. Ctrl+c Ctrl+c to evaluate the current top-level form.</p> <p> Prelude Install Guide</p> <p></p> <p> Doom Emacs is a community configuration for Emacs that provides a minimalistic configuration that is readily customisable.  Doom Emacs is most suited to those coming from Vim and have a strong experience for multi-modal editing.</p> <p> Practicalli Doom Emacs Book</p> <p> Practicalli Doom Emacs Config contains a customised configuration for Clojure development and supporting tools.</p> Free Desktop XDG ConfigClassic Config <p><pre><code>git clone https://github.com/practicalli/doom-emacs-config.git $XDG_CONFIG_HOME/doom`\n</code></pre> The Practicalli configuration should replace the <code>~/.config/doom/</code> directory created by the <code>doom install</code> command.</p> <p><pre><code>git clone https://github.com/practicalli/doom-emacs-config.git $HOME/.doom.d`\n</code></pre> The Practicalli configuration should replace the <code>~/.doom.d/</code> directory created by the <code>doom install</code> command.</p> <p> </p> <p>Emacs 29 is recommended as it includes native compilation support and optomised JSON support which is valuable for Language Server Protocol servers.</p> <p>Emacs is available for Linux, MacOSX and Windows.</p> Ubuntu / DebianHomebrew / MacOSXWindowsMsys2 <p><code>apt-cache show emacs</code> to check available versions of Emacs in the Ubuntu package manager. If version 28 is available, install Emacs using the Ubuntu package manager.</p> <pre><code>sudo apt install emacs\n</code></pre> <p>Additional versions of Emacs are available via the Ubuntu Emacs Team Personal Package Archive.</p> <p><code>sudo apt install emacs-snapshot</code> package to use the latest nightly build of Emacs, although be aware that some things may break.</p> Build Emacs 29 from source <p>Building Emacs 29 from source code on Ubuntu is relatively straight forward task, although it will take a little time to compile.  Building Emacs allows customisation of some features, such as native compilatin of elisp to enhance the performance of Emacs.</p> <p>Emacs Plus from Homebrew provides many options, including native compilation and Spacemacs Icon for application launchers.</p> <pre><code>brew tap d12frosted/emacs-plus`\nbrew install emacs-plus@28 --with-native-comp --with-spacemacs-icon\n</code></pre> <p>Emacs.app is installed to: <code>/usr/local/opt/emacs-plus@28</code></p> <p>Optionally run Emacs plus as a service <pre><code>brew services start d12frosted/emacs-plus/emacs-plus@28\n</code></pre></p> <p>Run <code>emacs</code></p> <p>Get a hot cup of something as Emacs native compilation compiles all the things.</p> <p>The Spacemacs README lists other options for MacOSX.</p> <p>Download Emacs-28.2 from the GNU repository and extract the zip file to <code>%AppData%/local/Programs/emacs</code>.</p> <p>Alternatively, if you are using the Chocolatey package manager then install Emacs version 28</p> <p>Add the Emacs directory to the <code>PATH</code> variable in your user account environment variables.</p> <p>To start Emacs run the command <code>runemacs.exe</code>.  You can also pin this to the start menu or task bar.</p> Access to common Unix tools <p>Command line tools, such as <code>diff</code>, are used by Emacs.  To have these command line tools available in Windows, install Emacs as above but then run emacs from a Unix shell such as GitBash.</p> <p>Install Emacs (64bits build) with the following:</p> <pre><code>pacman -S mingw-w64-x86_64-emacs\n</code></pre> <p>Once Emacs is installed, add the cider package for essential Clojure support.</p> <p>Cider Install Guide</p> <p></p> <p>Neovim is a hyper-extensible text editor that runs in a terminal, configured with the Lua programming language. Configuration can also be written in Fennel (a lisp dialect), using nfnl to generate Lua code.</p> <p>Neovim is based on multi-model editing (e.g. normal, insert, visual editing states) providing a highly effective tool for writing code, configuration and documentation.</p> <p>Neovim includes Treesitter which understands the syntax of a great many programming and configuration languages, which can be coupled with analysist from Language Sever Protocol (LSP) servers to provide live feedback on code quality.</p> <p></p> <p>Conjure provides Clojure interactive (REPL) development, supporting Clojure CLI, Leiningen and Babashka projects (as well as several other Lisp dialects and interesting languages)</p> <p>Try the Conjure interactive <code>:ConjureSchool</code> tutorial which only requires a recent version of neovim <pre><code>curl -fL conjure.fun/school | sh\n</code></pre> </p> <p><code>:q</code> to quit the tutorial.</p> Practicalli AstroNvimPracticalli NeovimSpaceVimVimIced <p> Practicalli Neovim - AstroNvim install</p> <p>AstroNvim community configuration for Neovim provides an engaging UI, using Lazy plugin manger and Mason to manage LSP servers, format &amp; lint tools.</p> <p> Practicalli AstroNvim Config provides a user configuration for Astronvim, including Conjure, parinfer, LSP server and treesitter parser for Clojure development.</p> <p> Practicalli Neovim provides an install and user guide for Neovim and Conjure for Clojure development, folloiwng a REPL driven workflow.</p> <p> </p> <p>Archived project - to be reimplemented using nfnl rather than aniseed.  Recommend using AstroNvim instead.</p> <p> Practicalli Neovim Config Redux configuration for Neovim which adds  a range of Neovim plugins for a rich development experience.</p> <ul> <li>mnemonic of key bindings to make adoptiong Neovim easier</li> <li>visual navigation for files, project, environment variables and any other list items</li> <li>version control and GitHub issue &amp; pull request management</li> </ul> <p> Conjure provides interactive environment for evaluating Clojure code and providing inline results (or see results in an Heads Up Display or Log buffer).</p> <p> Practicalli Neovim provides an install and user guide for Neovim and Conjure for Clojure development, folloiwng a REPL driven workflow.</p> <p></p> <p>SpaceVim is a fully featured vim experience that includes a minimal Clojure development environment based around vim-fireplace</p> <p>Follow the Quick Start Guide to install SpaceVim</p> <p>Add the Clojure layer to the SpaceVim custom configuration file ~/.SpaceVim.d/init.toml<pre><code>[[layers]]\n  name = \"lang#clojure\"\n</code></pre></p> <p>SpaceVim quickstart guide SpaceVim - Clojure Layer</p> <p></p> <p>Interactive Clojure Environment for Vim8/Neovim, aimed at the more experienced Vim/Neovim user.</p> <p>vim-iced uses vim-sexp for structural editing</p> <p>vim-plug is required to install the vim-iced packages.</p> <p>vim-iced documentation</p> <p></p> <p>VS Code is a freely available editor build on open source and available for Linux, MacOS and Microsoft Windows.</p> <p>VSCode Getting Started Guide</p> <p>VS Code has a large marketplace of extensions, proiding additional tools for a complete development environment.</p> <p>Calva is the most commonly used extension for Clojure support and aims to provide similar features to Emacs Cider (and uses some of the same Clojure libraries).</p> <p>Clojure CLI User Aliases not directly supported</p> <p>Calva does not support Clojure CLI user aliases directly (only project deps.edn).  A JSON mapping must be added to the Calva configuration for each user alias (duplicating configuration)</p> <p>Practicalli recommends starting the Clojure REPL in a terminal and specifying the required Clojure CLI user aliases, using Calva connect once the REPL has started.</p> <p>VSpaceCode provides a mnemonic menu to drive VS Code by keyboard alone, vim editing and rich Git client (edamagit).  VSpaceCode extension also provides key bindings for common Calva commands.  Users experienced with Neovim and Emacs (Spacemacs / Doom) will find this extension makes VS Code easiter to use than vanilla VS Code or VS Code with an Neovim backend.</p> <p>Clover provides a mininal, highly customisable environment using Socket REPL.</p> CalvaVSpaceCodeClover <p></p> <p>The Calva extension adds Clojure REPL support to VS Code editor, including Clojure LSP, formatting, structural editing and many other features.</p> <p>Calva is under active development and the #calva channel on the Clojurians Slack community can be supportive.</p> <p>Calva Getting Started Guide Calva - VS Code Marketplace</p> <p><p> </p></p> <p></p> <p>VSpaceCode is a Spacemacs-like community configuration for Microsoft VS Code. Drive VS Code entirely from the keyboard, using easy to remember mnemonic keys for all commands and full vim-stile editing tools.</p> <p>Calva extension must be added as it is not part of VSpaceCode, although Calva commands are included in the VSpaceCode mneomoic menu when a Clojure file is open.</p> <p>Edamagit is a sophisticated text based Git client (like magit for Emacs) is also included in the VSpacemacs extension.</p> <p>Practicalli VSpaceCode install guide Practicalli VSpaceCode user guide</p> <p></p> <p><p> </p></p> <p>Clover is a Socket REPL based development tool for Clojure with some ClojureScript support (not including Figwheel).</p> <p>Clojure GitLab repository includes usage details.</p> <p></p> <p>SublimeText 4 is a lightweight and feature rich text editor, especially of interest to those that like a simple and uncluttered UI.  SublimeText is a commercial project although has free trial version available (check conditions of use).</p> <p>Clojure-Sublimed provides Clojure support for SublimeText 4, with support for Clojure &amp; Edn syntax, code formatting and an nREPL client to connect to a Clojure REPL process.</p> <p>Tutkain is an Sublime 4 package that supports Clojure development (self-described as alpha software).</p> <p>Build configuration to start a REPL</p> <p>Clojure Sublime connects to a REPL via an nREPL server.  Run a terminal REPL using Clojure CLI, Leinginen (<code>lein repl</code>) or Shadow-cljs (<code>shadow-cljs watch app</code>)</p> <p>Alternatively, configure Clojure Sublimed to run a REPL process by creating a new build system via Tools \u00bb Build System \u00bb New Build System. The following example starts a Clojure CLI REPL with nREPL server and assumes Java and Clojure CLI are installed. <pre><code>{\"env\": {\"JAVA_HOME\": \"/path/to/java\"},\n \"cmd\": [\"/usr/local/bin/clojure\", \"-Sdeps\", \"{:deps {nrepl/nrepl {:mvn/version \\\"1.0.0\\\"}}}\", \"-M\", \"-m\", \"nrepl.cmdline\"]}\n</code></pre> Run a REPL process via Tools \u00bb Build With\u2026 and connect to the REPL using the command Clojure Sublimed: Connect</p> <p>SublimeText install Clojure-Sublimed install SublimeText Documentation</p> <p></p> <p>Pulsar Community-led Hyper-Hackable Editor is a very new project to create a community version of the Atom editor from GitHub.</p> <p>Chlorine plugin provides a Clojure and ClojureScript development environment using Socket-REPL integration</p> <p>Pulsar Community-led Hyper-Hackable Editor Pulsar Chlorine plugin</p> <p>Atom not actively developed</p> <p>Atom will be archived on December 15 2022 with no further updates from GitHub team</p> <p>Consider using VSCode with Clover or Calva plugin or help support the evolution of the Pulsar project</p> <p>Cursive may be an appropriate choice for people from a Java background who are already familiar with IntelliJ.  Cursive will run static analysis of Clojure code when opening a Clojure project, as IntelliJ does with other languages.</p> <p>Follow the Cursive user guide to configure IntelliJ and install Cursive.</p> <p>Requires license for commercial development</p> <p>There is a free license when development is not for commercial projects, however, a license must be purchased for each developer working on a commercial project.</p> <p>IntelliJ &amp; Cursive install guide</p> <p></p>"},{"location":"clojure-editors/clojure-lsp/","title":"Language Server Protocol","text":"<p> Language Server Protocol provides a standard to provide a common set of development tools, e.g.  code completion, syntax highlighting, refactor and language diagnostics.</p> <p>Each language requires a specific LSP server implementation.</p> <p>An editor or plugin provides an LSP client that uses data from language servers, providing information about source code and enabling development tools to understand the code structure.</p>"},{"location":"clojure-editors/clojure-lsp/#clojure-lsp","title":"Clojure LSP","text":"<p> clojure-lsp is an implementation of an LSP server for Clojure and ClojureScript languages.  Clojure LSP is built on top of  clj-kondo which provides the static analysis of Clojure and ClojureScript code.</p> <p>Most Clojure aware editors provide an LSP client.</p> <p></p>"},{"location":"clojure-editors/clojure-lsp/#install","title":"Install","text":"<p>Clojure LSP installation guide covers multiple operating systems.</p> LinuxHomebrew <p>Practicalli recommends downloading the <code>clojure-lsp-native-linux-amd64</code> from GitHub release page</p> <p>Extracts the <code>clojure-lsp</code> binary to <code>~/.local/bin/clojure-lsp</code></p> <p>Clojure LSP project provides a custom tap for installing the latest version.</p> <pre><code>brew install clojure-lsp/brew/clojure-lsp-native\n</code></pre> Homebrew default package deprecated <p>The <code>clojure-lsp</code> formula is deprecated and should not be used.</p> <p><code>brew remove clojure-lsp</code> if the default clojure-lsp was installed</p> <p>Check Clojure LSP server is working via the command line</p> <pre><code>clojure-lsp --version\n</code></pre> Editors may provide install mechanism for Clojure LSP <p>Spacemacs LSP layer will prompt to install a language server when first opening a file of a major mode where LSP is enabled.  E.g. when a Clojure related file is opened, the Clojure LSP server is downloaded if not installed (or not found on the Emacs path).</p> <p>Neovim package called mason manages the install of lint &amp; format tools as well as LSP servers, or an externally installed LSP server can also be used.</p> <p>VSCode Calva plugin includes the clojure-lsp server, although an external server can be configured.</p>"},{"location":"clojure-editors/clojure-lsp/#configure","title":"Configure","text":"Practicalli Clojure LSP Configuration <p>config.edn is the recommended configuration from Practicalli. <pre><code>;; ---------------------------------------------------------\n;; Clojure LSP user level (global) configuration\n;; https://clojure-lsp.io/settings/\n;;\n;; Complete config.edn example with default settings\n;; https://github.com/clojure-lsp/clojure-lsp/blob/master/docs/all-available-settings.edn\n;; default key/value are in comments\n;; ---------------------------------------------------------\n\n;; Refact config from all-available-settings example\n\n{;; ---------------------------------------------------------\n ;; Project analysis\n\n ;; auto-resolved for deps.edn, project.clj or bb.edn projects\n ;; :source-paths #{\"src\" \"test\"}\n\n ;; Include :extra-paths and :extra-deps from project &amp; user level aliases in LSP classpath\n ;;  :source-aliases #{:dev :test}\n :source-aliases #{:dev :test :dev/env :dev/reloaded}\n\n ;; Define a custom project classpath command, e.g. Clojure CLI\n ;; :project-specs [{:project-path \"deps.edn\"\n ;;                  :classpath-cmd [\"clojure\" \"-M:env/dev:env/test\" \"-Spath\"]}]\n ;; Check the default at clojure-lsp.classpath/default-project-specs\n ;; :project-specs []\n\n ;; ignore analyzing/linting specific paths\n :source-paths-ignore-regex [\"target.*\" \"build.*\" \"console-log-.*\"]\n\n ;; Additional LSP configurations to load from classpath\n ;; https://clojure-lsp.io/settings/#classpath-config-paths\n ;; :classpath-config-paths []\n\n ;; :paths-ignore-regex []\n\n ;; Watch for classpath changes\n ;; :notify-references-on-file-change true\n ;; :compute-external-file-changes true\n\n ;; Approach for linking dependencies\n ;; :dependency-scheme \"zipfile\"\n\n ;; generate and analyze stubs for specific namespaces on the project classpath\n ;; typically for closed source dependencies, e.g. datomic.api\n ;; https://clojure-lsp.io/settings/#stub-generation\n ;; :stubs {:generation {:namespaces #{}\n ;;                      :output-dir \".lsp/.cache/stubs\"\n ;;                     :java-command \"java\"}\n ;;        :extra-dirs []}\n\n ;; Java Sources from Ubuntu package openjdk-17-source\n ;; jdk-source-uri takes precedence\n ;; :java\n ;; {:jdk-source-uri \"https://raw.githubusercontent.com/clojure-lsp/jdk-source/main/openjdk-19/reduced/source.zip\"\n ;;  :home-path nil ;; jdk-source-uri takes precedence\n ;;  :download-jdk-source? false\n ;;  :decompile-jar-as-project? true}\n ;; :java\n ;; {:jdk-source-uri \"file:///usr/lib/jvm/openjdk-17/lib/src.zip\"}\n :java nil\n\n ;; End of Project analysis\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Linter configuration\n\n ;; clj-kondo Linter rules\n ;; https://github.com/clj-kondo/clj-kondo/blob/master/doc/config.md#enable-optional-linters\n ;; :linters {:clj-kondo {:level :on\n ;;                      :report-duplicates true\n ;;                      :ns-exclude-regex \"\"}\n ;;          :clj-depend {:level :info}} ;; Only if any clj-depend config is found\n\n ;; asynchronously lint project files after startup, for features like List project errors\n ;; :lint-project-files-after-startup? true\n\n ;; copy clj-kondo hooks configs exported by libs on classpath during startup\n ;; :copy-kondo-configs? true\n\n ;; End of Linter configuration\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Refactor code\n\n ;; Namespace format\n ;; :clean {:automatically-after-ns-refactor true\n ;;         :ns-inner-blocks-indentation :next-line\n ;;         :ns-import-classes-indentation :next-line\n ;;         :sort {:ns true\n ;;                :require true\n ;;                :import true\n ;;                :import-classes {:classes-per-line 3} ;; -1 for all in single line\n ;;                :refer {:max-line-length 80}}}\n\n  ;; Do not sort namespaces\n :clean {sort {:ns      false\n               :require false\n               :import  false}}\n\n ;; Automatically add ns form to new Clojure/Script files\n ;; :auto-add-ns-to-new-files? true\n\n ;; use ^private metadata rather than defn-\n ;; :use-metadata-for-privacy? false\n :use-metadata-for-privacy? true\n\n ;; Keep parens around single argument functions in thread macro\n ;; :keep-parens-when-threading? false\n :keep-parens-when-threading? true\n\n ;; End of Refactor code\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Clojure formatting configuration - cljfmt\n\n ;; location of cljfmt configuration for formatting\n ;; Path relative to project root or an absolute path\n ;; :cljfmt-config-path \".cljfmt.edn\"\n :cljfmt-config-path \"cljfmt.edn\"\n\n ;; Specify cljfmt configuration within Clojure LSP configuration file\n ;; :cljfmt {}\n\n ;; End of Clojure formatting configuration - cljfmt\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Visual LSP components\n\n ;; :hover {:hide-file-location? false\n ;;         :arity-on-same-line? false\n ;;         :clojuredocs true}\n\n ;; :completion {:additional-edits-warning-text nil\n ;;              :analysis-type :fast-but-stale}\n\n ;; :code-lens {:segregate-test-references true}\n\n ;; LSP semantic tokens server support for syntax highlighting\n ;; :semantic-tokens? true\n\n ;; Documentation artefacts\n ;; :document-formatting?       true\n ;; :document-range-formatting? true\n\n ;; End of Visual LSP components\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; LSP general configuration options\n\n ;; Exit clojure-lsp if any errors found, e.g. classpath scan failure\n ;; :api {:exit-on-errors? true}\n\n ;; Synchronise whole buffer `:full` or only related changes `:incremental`\n ;; :text-document-sync-kind :full\n\n ;; End of LSP general configuration options\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; File locations\n\n ;; project analysis cache to speed clojure-lsp startup\n ;; relative path to project root or absolute path\n ;; :cache-path \".lsp/.cache\"\n\n ;; Absolute path\n ;; :log-path \"/tmp/clojure-lsp.*.out\"\n\n ;; End of file locations\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; LSP snippets\n ;; https://clojure-lsp.io/features/#snippets\n\n :additional-snippets\n [;; Documentation / comments\n\n  {:name \"comment-heading\"\n   :detail \"Comment Header\"\n   :snippet\n   \";; ---------------------------------------------------------\n    ;; ${1:Heading summary title}\n    ;;\n    ;; ${2:Brief description}\\n;; ---------------------------------------------------------\\n\\n$0\"}\n\n  {:name \"comment-separator\"\n   :detail \"Comment Separator\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\"}\n\n  {:name \"comment-section\"\n   :detail \"Comment Section\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\\n\\n\n    ;; End of $1\\n;; ---------------------------------------------------------\\n\\n\"}\n\n  {:name \"wrap-reader-comment\"\n   :detail \"Wrap current expression with Comment Reader macro\"\n   :snippet \"#_$current-form\"}\n\n  {:name \"rich-comment\"\n   :detail \"Create rich comment\"\n   :snippet\n   \"(comment\n      $0\n  #_()) ;; End of rich comment\"}\n\n  {:name \"rich-comment-rdd\"\n   :detail \"Create comment block\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n   (comment\n     $0\n   #_()) ; End of rich comment\"}\n\n  {:name \"rich-comment-hotload\"\n   :detail \"Rich comment library hotload\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n    (comment\n      ;; Add-lib library for hot-loading\n      (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n      (add-libs '{${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$3})\n      $0\n    #_()) ; End of rich comment block\"}\n\n  {:name \"wrap-rich-comment\"\n   :detail \"Wrap current expression with rich comment form\"\n   :snippet\n   \"(comment\n      $current-form\n      $0\n   #_()) ;; End of rich comment\"}\n\n  ;; Core functions\n\n  {:name \"def\"\n   :detail \"def with docstring\"\n   :snippet \"(def ${1:name}\\n  \\\"${2:doc-string}\\\"\\n  $0)\"}\n\n  {:name \"def-\"\n   :detail \"def private\"\n   :snippet \"(def ^:private ${1:name}\\n  \\\"${2:doc-string}\\\"\\n $0)\"}\n\n  {:name \"defn\"\n   :detail \"Create public function\"\n   :snippet \"(defn ${1:name}\\n  \\\"${2:doc-string}\\\"\\n   [${3:args}]\\n  $0)\"}\n\n  {:name \"defn-\"\n   :detail \"Create public function\"\n   :snippet \"(defn ^:private ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n\n  {:name \"ns\"\n   :detail \"Create ns\"\n   :snippet \"(ns ${1:name}\\n  \\\"${2:doc-string}\\\"\\n  ${3:require})\"}\n\n  ;; Clojure CLI alias snippets\n\n  {:name \"deps-alias\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}}$0\"}\n\n  {:name \"deps-alias-main\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :main-opts [\\\"-m\\\" \\\"${4:main namespace}\\\"]}$0\"}\n\n  {:name \"deps-alias-exec\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :exec-fn ${4:domain/function-name}\n     :exec-args {${5:key value}}}$0\"}\n\n  {:name \"deps-alias-main-exec\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :main-opts [\\\"-m\\\" \\\"${4:main namespace}\\\"]\n     :exec-fn ${4:domain/function-name}\n     :exec-args {${5:key value}}}$0\"}\n\n  {:name \"deps-maven\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$0\"}\n\n  {:name \"deps-git\"\n   :detail \"deps.edn Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n       {:git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-git-tag\"\n   :detail \"Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/tag \\\"${2:git-tag-value}\\\"\n       :git/sha \\\"${3:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-git-url\"\n   :detail \"Git URL dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/url \\\"https://github.com/$1\\\"\n       :git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-local\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:local/root \\\"${2:/path/to/project/root}\\\"}$0\"}\n\n   ;; Requiring dependency snippets\n\n  {:name \"require-rdd\"\n   :detail \"require for rich comment experiments\"\n   :snippet \"(require '[${1:namespace} :as ${2:alias}]$3)$0\"}\n\n  {:name \"require\"\n   :detail \"ns require\"\n   :snippet \"(:require [${1:namespace}])$0\"}\n\n  {:name \"require-refer\"\n   :detail \"ns require with :refer\"\n   :snippet \"(:require [${1:namespace} :refer [$2]]$3)$0\"}\n\n  {:name \"require-as\"\n   :detail \"ns require with :as alias\"\n   :snippet \"(:require [${1:namespace} :as ${2:alias}]$3)$0\"}\n\n  {:name \"use\"\n   :detail \"require refer preferred over use\"\n   :snippet \"(:require [${1:namespace} :refer [$2]])$0\"}\n\n   ;; Unit Test snippets\n\n  {:name \"deftest\"\n   :detail \"deftest clojure.test\"\n   :snippet\n   \"(deftest ${1:name}-test\n            (testing \\\"${2:Context of the test assertions}\\\"\n            (is (= ${3:assertion-values}))$4)) $0\"}\n\n  {:name \"testing\"\n   :detail \"testing asserting group for clojure.test\"\n   :snippet \"(testing \\\"${1:description-of-assertion-group}\\\"\\n $0)\"}\n\n  {:name \"is\"\n   :detail \"assertion for clojure.test\"\n   :snippet \"(is (= ${1:function call} ${2:expected result}))$0\"}\n\n   ;; ---------------------------------------------------------\n   ;; Clojure LSP and Clj-kondo snippets\n\n  {:name \"lsp-ignore-redefined\"\n   :detail \"Ignore redefined Vars\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n            $0\"}\n\n   ;; End of Clojure LSP and Clj-kondo snippets\n   ;; ---------------------------------------------------------\n  ]\n  ;; End of LSP snippets\n  ;; ---------------------------------------------------------\n\n }\n</code></pre></p> <p>Include <code>:extra-paths</code> and <code>:extra-deps</code> from project &amp; user level aliases in LSP classpath.  e.g. support a custom <code>user</code> namespace in <code>dev/user.clj</code></p> <pre><code> :source-aliases #{:dev :test :env/dev :env/test :lib/reloaded}\n</code></pre> <p>Include Java Sources installed via Debian / Ubuntu package <code>openjdk-21-source</code> to support calls to Java Objects and Methods.</p> <pre><code> :java\n {:jdk-source-uri       \"file:///usr/lib/jvm/openjdk-21/lib/src.zip\" ;;\n  :home-path            nil ;; jdk-source-uri takes precedence\n  :download-jdk-source? false}\n</code></pre> <p>Disable Java analysis</p> <p>If not using Java Interop with Clojure, it can be an advantage to disable the Java analysis.  This should remove Java functions from autocomplete.</p> <pre><code>:java nil\n</code></pre> <p>Clean namespace <code>ns</code> forms but do not sort require names</p> <pre><code> :clean {:automatically-after-ns-refactor true\n         :ns-inner-blocks-indentation     :next-line\n         :ns-import-classes-indentation   :next-line\n         :sort {:ns      false\n                :require false\n                :import  false\n                :import-classes {:classes-per-line 3} ;; -1 for all in single line\n                :refer {:max-line-length 80}}}\n</code></pre> <p>Use <code>^private</code> metadata for private function definitions rather than <code>defn-</code></p> <pre><code> :use-metadata-for-privacy? true\n</code></pre> <p>Location of cljfmt configuration for formatting, path relative to project root.  The defaults for cljfmt are used, except <code>:remove-consecutive-blank-lines?</code> which is set to false to enable more readable code.</p> <pre><code> :cljfmt-config-path \"cljfmt.edn\"\n</code></pre> <p>cljfmt configuration included example <code>:indents</code> rules for clojure.core, compojure, fuzzy rules and examples used by the Clojure LSP maintainer.</p>"},{"location":"clojure-editors/clojure-lsp/#practicalli-snippets","title":"Practicalli snippets","text":"<p>Practicalli Snippets are defined in the <code>:additional-snippets</code> section of the Practicalli Clojure LSP config.</p>"},{"location":"clojure-editors/clojure-lsp/#docs-comments","title":"Docs / comments","text":"<ul> <li><code>comment-heading</code> - describe purpose of the namespace</li> <li><code>comment-separator</code> - logically separate code sections, helps identify opportunities to refactor to other name spaces</li> <li><code>comment-section</code> - logically separate large code sections with start and end line comments</li> <li><code>wrap-reader-comment</code> - insert reader comment macro, <code>#_</code> before current form, informing Clojure reader to ignore next form</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#repl-driven-development","title":"Repl Driven Development","text":"<ul> <li><code>rich-comment</code> - comment block</li> <li><code>rich-comment-rdd</code> - comment block with ignore :redefined-var for repl experiments</li> <li><code>rich-comment-hotload</code> - comment block with add-libs code for hotloading libraries in Clojure CLI repl</li> <li><code>wrap-rich-comment</code> - wrap current form with comment reader macro</li> <li><code>require-rdd</code> - add a require expression, for adding a require in a rich comment block for RDD</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#standard-library-functions","title":"Standard library functions","text":"<ul> <li><code>def</code> - def with docstring</li> <li><code>def-</code> - private def with docstring</li> <li><code>defn</code> - defn with docstring</li> <li><code>defn-</code> private defn with docstring</li> <li><code>ns</code> - namespace form with docstring</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#clojure-cli-depsedn-aliases","title":"Clojure CLI deps.edn aliases","text":"<ul> <li><code>deps-alias</code> - add Clojure CLI alias</li> <li><code>deps-maven</code> - add a maven style dependency</li> <li><code>deps-git</code> - add a git style dependency using <code>:git/sha</code></li> <li><code>deps-git-tag</code> - as above including <code>:git/tag</code></li> <li><code>deps-git-url</code> - add git style dependency using git url (url taken from dependency name as it is typed - mirrored placeholder)</li> <li><code>deps-local</code> - add a <code>:local/root</code> dependency</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#requiring-dependencies","title":"Requiring dependencies","text":"<ul> <li><code>require-rdd</code> - add a require expression, for adding a require in a rich comment block for RDD</li> <li><code>require</code> - simple require</li> <li><code>require-refer</code> - require with <code>:refer</code></li> <li><code>require-as</code> - require with <code>:as</code> alias</li> <li><code>use</code> - creates a require rather than the more troublesome use</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#unit-testing","title":"Unit testing","text":"<ul> <li><code>deftest</code> - creates a deftest with testing directive and one assertion</li> <li><code>testing</code> - creates a testing testing directive and one assertion</li> <li><code>is</code> - an assertion with placeholders for test function and expected results</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#references","title":"References","text":"<ul> <li>LSP mode - A guide on disabling / enabling features - if the Emacs UI is too cluttered or missing visual features</li> <li>Configure Emacs as a Clojure IDE</li> <li>Language Server Protocol support for Emacs</li> </ul>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/","title":"Practicalli Snippets for Clojure LSP","text":"<p>Custom snippets created by Practicalli and added via the <code>:additional-snippets</code> key in the Clojure LSP configuration (<code>.lsp/config.edn</code> or user level configuration).  Snippets are defined as a vector of hash-maps</p> <pre><code>{:additional-snippets [{} {} {} ,,,]}\n</code></pre> <p>Practicalli Snippets available in practicalli/clojure-lsp-config</p> <p>Move or delete the clojure configuration directory and clone the  Practicalli Clojure CLI Config</p>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#documentation","title":"Documentation","text":"<p>A comment heading to describe the purpose and important information about the current namesapce.</p> <pre><code>  {:name \"comment-heading\"\n   :detail \"Comment Header\"\n   :snippet\n   \";; ---------------------------------------------------------\n    ;; ${1:Heading summary title}\n    ;;\n    ;; ${2:Brief description}\\n;; ---------------------------------------------------------\\n\\n$0\"}\n</code></pre> <p>A comment separator for marking logical sections within a namespace, useful for navigating code and identifying opportunities to refactor a namespace into multiple namespaces.</p> <pre><code>  {:name \"comment-separator\"\n   :detail \"Comment Separator\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\"}\n</code></pre> <p>A comment section with start and end titles for marking logical sections within a namespace, again for navigation and identifying opportunities to refactor a namespace.</p> <pre><code>  {:name \"comment-section\"\n   :detail \"Comment Section\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\\n\\n\n    ;; End of $1\\n;; ---------------------------------------------------------\\n\\n\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#repl-driven-development","title":"REPL Driven Development","text":"<p>A rich comment block typically used to hold function calls to show how to make use of the important aspects of the current namespace.  For example, calls to <code>start</code>, <code>restart</code>, <code>stop</code> functions in a namespace that defines the service life-cycle.</p> <p>This provides a live executable guide to using the namespace, without being called if the whole namespace is evaluated.</p> <p>A commented expression is placed before the closing paren to ensure that closing paren is not folded up into the previous line.  This makes it easier to add further code to the rich comment block.</p> <pre><code>  {:name \"rich-comment\"\n   :detail \"Create rich comment\"\n   :snippet\n   \"(comment\n      $0\n  #_()) ;; End of rich comment\"}\n</code></pre> <p>A modified rich comment block with clj-kondo configuration to suppress warnings for duplicate function definition names, supporting alternative function implementations as part of a REPL driven development workflow.</p> <pre><code>  {:name \"rich-comment-rdd\"\n   :detail \"Create comment block\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n   (comment\n     $0\n   #_()) ;; End of rich comment\"}\n</code></pre> <p>Wrap an existing form in a rich comment</p> <pre><code>  {:name \"wrap-rich-comment\"\n   :detail \"Wrap current expression with rich comment form\"\n   :snippet\n   \"(comment\n      $current-form\n      $0\n   #_()) ;; End of rich comment\"}\n</code></pre> <p>Comment an existing form with the Clojure Comment macro, <code>_#</code></p> <pre><code>  {:name \"wrap-reader-comment\"\n   :detail \"Wrap current expression with Comment Reader macro\"\n   :snippet \"#_$current-form\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#hot-loading-library-dependencies","title":"Hot loading library dependencies","text":"<p>Clojure CLI projects can hotload library dependencies into a running Clojure REPL.  This requires starting a REPL with the <code>clojure.tools.deps.alpha</code> library as a dependency which can be done by including the <code>:lib/hotload</code> alias from practicalli/clojure-deps-edn.  Note this library is alpha and the API could change in future.</p> <p>Create a rich comment block that requires the <code>clojure.tools.deps.alpha</code> namespace and an <code>add-libs</code> expression to hotload one or more libraries in a hash-map.  Tab stops with placeholders are included for adding the first library to hotload.</p> <pre><code>  {:name \"rich-comment-hotload\"\n   :detail \"Rich comment library hotload\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n    (comment\n      ;; Add-lib library for hot-loading\n      (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n      (add-libs '{${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$3})\n      $0\n    #_()) ;; End of rich comment block\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#core-functions","title":"Core functions","text":"<p>Create a public var using a <code>def</code> form with a doc-string, with placeholders for name and value.</p> <pre><code>  {:name \"def\"\n   :detail \"def with docstring\"\n   :snippet \"(def ${1:name}\\n  \\\"${2:docstring}\\\"\\n  $0)\"}\n</code></pre> <p>Create a private var using a <code>def</code> form with <code>^:private</code> meta data and a doc-string, with placeholders for name and value.</p> <pre><code>  {:name \"def-\"\n   :detail \"def private\"\n   :snippet \"(def ^:private ${1:name}\\n  \\\"${2:doc-string}\\\"\\n $0)\"}\n</code></pre> <p>A <code>defn</code> form with name, doc-string and args tab-stops</p> <pre><code>  {:name \"defn\"\n   :detail \"Create public function\"\n   :snippet \"(defn ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n</code></pre> <p>A <code>defn</code> form with private metatdata. Including name, doc-string and args tab-stops</p> <pre><code>  {:name \"defn-\"\n   :detail \"Create public function\"\n   :snippet \"(defn ^:private ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n</code></pre> <p>A namespace form with name, doc-string and require tab-stop.</p> <pre><code>  {:name \"ns\"\n   :detail \"Create ns\"\n   :snippet \"(ns ${1:name}\\n  \\\"${2:docstring}\\\"\\n  ${3:require})\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#clojure-cli-aliases-and-library-dependencies","title":"Clojure CLI aliases and library dependencies","text":"<p>Add Clojure CLI alias to <code>deps.edn</code>, with an <code>:extra-paths</code> and <code>:extra-deps</code> section</p> <pre><code>  {:name \"deps-alias\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}}$0\"}\n</code></pre> <p>Add a Maven style dependency to a Clojure CLI <code>deps.edn</code> project.</p> <pre><code>  {:name \"deps-maven\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$0\"}\n</code></pre> <p>Add a dependency from a Git repository, where the library is named after the remote Git repository, i.e io.github.user|org/library-name for the GitHub repository <code>https://github.com/user|org/library-name</code>.</p> <p>The <code>:git/sha</code> defines a specific commit to use for the dependency.</p> <pre><code>  {:name \"deps-git\"\n   :detail \"deps.edn Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n       {:git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n</code></pre> <p>Additionally a Git tag can be specified, enabling the use of the short SHA value for <code>:git/sha</code> (short sha is the first 7 characters of the 40 character SHA-1 value).</p> <p>A Git client can obtain the short form of a SHA from a Git repository</p> <pre><code>git rev-parse --short 1e872b59013425b7c404a91d16119e8452b983f2\n</code></pre> <pre><code>  {:name \"deps-git-tag\"\n   :detail \"Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/tag \\\"${2:git-tag-value}\\\"\n       :git/sha \\\"${3:git-sha-value}\\\"}$0\"}\n</code></pre> <p>If a library is not named after the domain of the Git repository, the URL of the Git repository must be specified using the <code>:git/url</code> key.</p> <pre><code>  {:name \"deps-git-url\"\n   :detail \"Git URL dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/url \\\"https://github.com/$1\\\"\n       :git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n</code></pre> <p>Add a library dependency that is a local Clojure project.</p> <pre><code>  {:name \"deps-local\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:local/root \\\"${2:/path/to/project/root}\\\"}$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#require-library-dependencies","title":"Require Library Dependencies","text":"<p>Require a library when using REPL driven development in a rich comment block, adding a <code>(require ,,,)</code> form when evaluating the use of a library without forcing it to be loaded when loading the namespace.</p> <pre><code>  {:name \"require-rdd\"\n   :detail \"require for rich comment experiments\"\n   :snippet \"(require '[${1:namespace} :as ${2:alias}]$3)$0\"}\n</code></pre> <p>A basic <code>:require</code> expression for an <code>ns</code> form.</p> <pre><code>  {:name \"require\"\n   :detail \"ns require\"\n   :snippet \"(:require [${1:namespace}])$0\"}\n</code></pre> <p>A <code>:require</code> expression for an <code>ns</code> form, including a <code>:as</code> directive to define an alias for the required namespace.</p> <pre><code>  {:name \"require-as\"\n   :detail \"ns require with :as alias\"\n   :snippet \"(:require [${1:namespace} :as ${2:alias}]$3)$0\"}\n</code></pre> <p>A <code>:require</code> expression for an <code>ns</code> form, including a <code>:refer</code> directive to include specific function definitions and vars by name.</p> <pre><code>  {:name \"require-refer\"\n   :detail \"ns require with :refer\"\n   :snippet \"(:require [${1:namespace} :refer [$2]]$3)$0\"}\n</code></pre> <p>It is idiomatic to use require with refer to pull in specific functions and vars from another namespace.  The <code>use</code> function is not recommended as it can easily pull more transitive dependencies into the current namespace, causing unexpected results</p> <pre><code>  {:name \"use\"\n   :detail \"require refer preferred over use\"\n   :snippet \"(:require [${1:namespace} :refer [$2]])$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#clojuretest-snippets","title":"Clojure.test snippets","text":"<p>When writing a <code>deftest</code>, a new assertion written may be better in a new group.  The <code>testing</code> snippet will create a new <code>testing</code> form and pull in the following assertion.</p> <pre><code>{:name \"deftest\"\n :detail \"deftest clojure.test\"\n :snippet\n \"(deftest ${1:name}-test\n    (testing \\\"${2:Context of the test assertions}\\\"\n      (is (= ${3:assertion-values}))$4))\n  $0\"}\n</code></pre> <p>Create a new assertion group using the <code>clojure.test/testing</code> form.</p> <p>Using <code>testing</code> before an assertion form pull that assertion into the group</p> <pre><code>  {:name \"testing\"\n   :detail \"testing clojure.test\"\n   :snippet \"(testing \\\"${1:description-of-assertion-group}\\\"\\n $0)\"}\n</code></pre> <p>Define an <code>is</code> assertion for a <code>deftest</code></p> <pre><code>  {:name \"is\"\n   :detail \"assertion for clojure.test\"\n   :snippet \"(is (= ${1:function call} ${2:expected result}))$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/snippets/","title":"Clojure LSP Snippets","text":"<p>Custom snippets are defined in the Clojure LSP EDN configuration using the <code>:additional-snipets</code> key.  The snippet body uses the same tab stop and placeholder syntax as Yasnipets, although the body is contained within a string.</p> <p>Built-in snippets can include Clojure code for generating the text of the snippet when expanded.  Custom snippets do not currently support evaluation of code in the snippet.</p> Clojure LSP Configuration locations <p>Project specific configuration resides in <code>.lsp/config.edn</code></p> <p>User level configuration is either <code>$XDG_CONFIG_HOME/clojure-lsp/config.edn</code> or <code>$HOME/.clojure-lsp/config</code></p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-definition","title":"Snippet definition","text":"<p>The <code>:additional-snippets</code> key is associated with a vector or hash-maps, <code>[{}{},,,]</code> with each hash-map defining a snippet using the keys:</p> <p><code>:name</code> - name of the snippet, typed into the editor for completion</p> <p><code>:detail</code> - a meaningful description of the snippet</p> <p><code>:snippet</code> - the definition of the snippet, with tab stops and current-form syntax</p> <p>The <code>:snippet</code> can be any text, ideally with syntax that is correct for the particular language</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-tab-stops","title":"Snippet Tab Stops","text":"<p>Include <code>$</code> with a number, e.g. <code>$1</code>,<code>$2</code>,<code>$3</code>,  to include tab stops in the snippet.  Once the snippet code has been generated, <code>TAB</code> key jumps through the tab stops in sequence, allowing customisation of a generic snippet.</p> <p><code>$0</code> marks the final position of the cursor, after which <code>TAB</code> has no more positions in the snippet to jump to.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-current-form","title":"Snippet current-form","text":"<p>When a Clojure LSP snipped includes <code>$current-form</code> then typing a snippet name in front of an existing Clojure form includes that form in the generated code.</p> <pre><code>{:additional-snippets [{:name \"wrap-let-sexpr\"\n                        :detail \"Wrap current sexpr in let\"\n                        :snippet \"(let [$1 $current-form] $0)\"}]}\n</code></pre> <p>Limited scope with current-form</p> <p>A Snippet including <code>$current-form</code> is only active when typed in front of an existing expression.  A snippet is not recognised when typed at the top level.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#placeholders","title":"Placeholders","text":"<p>Tab Stops can also include default values or text used as hint on what each tab stop value is for.  These are referred to as placeholders.</p> <p><code>${1:default-value}</code> is the form of a placeholder for tab stop 1.  When the cursor tabs to tab stop 1, the default-value text is highlighted and replaces as soon as characters are typed.</p> <p>Placeholder text is not replaced for <code>$0</code> tab-stop, as the snippet interaction is effectively over at this point.</p> <p>The <code>deftest</code> custom snippet shows examples of placeholders for three tab stops.</p> <pre><code>{:name \"deftest\"\n :detail \"deftest clojure.test\"\n :snippet\n \"(deftest ${1:name}-test\n    (testing \\\"${2:Context of the test assertions}\\\"\n      (is (= ${3:assertion-values}))$4))\n  $0\"}\n</code></pre> <p>Escape string quotes in snippet body</p> <p>Use <code>\\</code> character before the <code>\"</code> character within the snippet body.  For example, doc-strings in <code>defn</code> function definitions or the string in <code>testing</code> function.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#code-driven-snippet","title":"Code driven snippet","text":"<p>The built-in <code>defn</code> snippet uses Clojure code to help generate the snippet.</p> <p><code>%s</code> is a substitution point within a snippet, used by the standard Clojure <code>format</code> command, used to included either <code>defn ^:private</code> or <code>defn-</code>, depending on the value returned from the <code>if</code> expression.</p> <p><code>:use-metadata-for-privacy?</code> is a key from the Clojure LSP configuration</p> <pre><code> {:label \"defn-\"\n  :detail \"Create private function\"\n  :insert-text (format \"(defn%s ${1:name} [$2]\\n  ${0:body})\"\n                       (if (:use-metadata-for-privacy? settings)\n                         \" ^:private\"\n                         \"-\"))}\n</code></pre> <p>The syntax for built-in snippets is slightly different that the <code>:additional-syntax</code> form.  The internal form uses <code>:label</code> for <code>:name</code> and <code>:insert-text</code> for <code>:snippet</code>.</p> <p>Code supported only in built-in snippets</p> <p>Clojure code only works for built-in snippets and not for <code>:additional-snippets</code>.</p> <p>Clojure LSP is compiled by Graal to a native binary, including the built-in snippets.  To include Clojure code in a snippet then consider submitting a pull request to the Clojure LSP project to add a built-in snippet.</p>"},{"location":"clojure-spec/","title":"Clojure Specifications","text":"<p>Clojure Spec is a library for defining specifications around data and functions to test for correctness.</p> <p>A spec defines the expected shape of specific values in Clojure and specs are intended to be used across multiple projects.  Specifications for more complex values are composed of specific value specifications, providing a flexible way to define what key parts of the system should look like.</p> <p>Clojure specs are used to generate comprehensive test data, identifying more scenarios and edge cases with less code.</p> <p>Spec is included in Clojure version 1.9 onward and can be used by requiring the <code>clojure.spec.alpha</code> in the REPL or in namespaces of a Clojure project.</p>"},{"location":"clojure-spec/#recommended-reading","title":"Recommended Reading","text":"<p>What is Clojure spec - an illustrated guide</p>"},{"location":"clojure-spec/#purpose-of-clojure-spec","title":"Purpose of Clojure spec","text":"<p>A summary highlighting the common purposes that Clojure Spec is used for</p> Purpose Description Living documentation Use spec to include specifications in Function documentation (<code>fdef</code>) Data Validation Ensure the data entering and leaving the system or its key functions are of the correct form Test Data Generation Provide extensive test data coverage with minimal code maintenance Generative testing of functions Test functions using their spec defined contract (<code>fdef</code>) Generative scenario testing Specific correct usage paths for known states Development time checking Instrument functions to ensure correctness Derive code from specifications Specify a system of record for data structures, internal and external to the system."},{"location":"clojure-spec/#example-use-cases","title":"Example use cases","text":"<ul> <li>API requests (schema is often used here, but so can spec)</li> <li>Checking data pulled from / pushed to message systems (e.g. Kafka, TIBCO)</li> <li>Data specifications (eg. Vega-lite)</li> </ul>"},{"location":"clojure-spec/#example-code","title":"Example code","text":"<p> practicalli/leveraging-spec</p> <p>practicalli/leveraging-spec - basic examples of using spec, following the Practicalli Spec broadcasts</p>"},{"location":"clojure-spec/#understanding-the-basics-of-clojure-spec","title":"Understanding the basics of Clojure Spec","text":""},{"location":"clojure-spec/#trying-clojurespec","title":"Trying clojure.spec","text":"<p>Follow the examples in these two excellent videos</p> <p> </p> <p> </p>"},{"location":"clojure-spec/#why-is-the-spec-library-called-alpha","title":"Why is the spec library called alpha?","text":"<p>The library is called <code>clojure.spec.alpha</code> as the design of spec is still evolving and there may be some changes to the design in later versions.  Clojure aims for backwards compatibility, so new versions typically do not break existing use of libraries.</p> <p>There are some important changes being developed for spec version 2 and a few things may change, however, the large majority of Spec will remain the same and is safe to use.</p>"},{"location":"clojure-spec/#references","title":"References","text":"<p>spec guide - clojure.org Introducing clojure.spec clojure.spec - rational and overview</p> <p>spec.alpha API reference</p> <p>How do you use clojure.spec - Sean Corfield</p> <p> Specifications for <code>clojure.core</code></p> <p> Leveraging clojure.spec - Stuart Halloway  spec.test - Stuart Halloway</p> <p>Clojure Spec: Expressing Data Constraints without Types</p>"},{"location":"clojure-spec/add-spec-to-projects/","title":"Add Spec to a project","text":"<p>Create a new project or clone  practicalli/leveraging-spec which includes several examples of using Clojure Spec.</p> Create new projectClone Practicalli Leveraging Spec project <p>Create a new Clojure CLI project using the  Practicalli project templates </p> Create new project<pre><code>clojure -T:project/create :template practicalli/minimal :name practicalli/leveraging-spec\n</code></pre>  Practicalli Clojure CLI Config - :project/create alias <p> Practicalli Clojure CLI Config repository includes the <code>:project/create</code> alias for creating new Clojure projects from a template using <code>deps-new</code>.</p> <p>The project is created with Clojure as a dependency, which includes the <code>clojure.spec.alpha</code> library.</p> <p>Clojure 1.9.0 or higher versions include Clojure Spec.  Clojure 1.11.1 is recommended.</p> <p> practicalli/leveraging-spec project includes Clojure Spec examples for values and functional arguments, along with unit tests using clojure spect-test.</p> <pre><code>https://github.com/practicalli/leveraging-spec.git\n</code></pre>"},{"location":"clojure-spec/add-spec-to-projects/#project-dependencies","title":"Project Dependencies","text":"<p>Clojure Spec is included in Clojure so only <code>org.clojure/clojure</code> dependency is required in the <code>deps.edn</code> file for the project.</p> <p>Clojure project dependency</p> deps.edn<pre><code>{:paths [\"src\" \"resources\"]\n :deps {org.clojure/clojure {:mvn/version \"1.11.1\"}}}\n</code></pre>"},{"location":"clojure-spec/add-spec-to-projects/#use-spec-in-namespace","title":"Use spec in namespace","text":"<p>Require the <code>clojure.spec.alpha</code> namespace in the <code>ns</code> definition using the <code>spec</code> alias name.  Practicalli recommends using <code>spec</code> (rather than <code>s</code> as it is much clearer as to where the functions are defined)</p> <p>Clojure project dependency</p> <pre><code>(ns practicalli.leveraging-spec\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>Evaluate the namespace definition to start using the functions from the namespace.</p> <p></p> <p>All functions from <code>clojure.spec.alpha</code> are now accessible using the <code>spec</code> alias, e.g. <code>spec/conform</code>, <code>spec/valid?</code>, <code>spec/def</code>.</p>"},{"location":"clojure-spec/add-spec-to-projects/#testing-with-spec","title":"Testing with spec","text":"<p>Add the <code>clojure.spec.test.alpha</code> using the <code>spec-test</code> alias, along with <code>clojure.spec.test.alpha</code> as <code>spec</code> alias</p> <p>Clojure project dependency</p> src/practicalli/leveraging_spec.clj<pre><code>(ns practicalli.leveraging-spec\n  (:require\n    [clojure.spec.alpha :as spec]\n    [clojure.spec.test.alpha :as spec-test]))\n</code></pre>"},{"location":"clojure-spec/organising-specs/","title":"Organizing Specifications","text":"<p>Data and function definition specifications are typically placed in a dedicated <code>specification</code> namespaces, e.g <code>src/domain/project/specification.clj</code>.  </p> <p>Add the data specifications (<code>spec/def</code>), custom predicate functions and function specifications (<code>spec/fdef</code>) to the <code>specifications</code> namespace.</p> <p>Specifications for an architecture layer can be organised next to the namespaces managing the layer, e.g. database. </p> <p>Migrate specifications to a library once they are applicable to multiple projects.</p>"},{"location":"clojure-spec/organising-specs/#instrumenting-functions","title":"Instrumenting functions","text":"<p>Add <code>spec-test/instrument</code> expressions to the <code>specifications</code> file, after the <code>spec/fdef</code> expressions.</p> <p>Rather than create individual expressions, create a <code>clojure.core/def</code> to contain a collection of all the <code>spec/fdef</code> expressions.  This list can then be used to <code>instrument</code> and <code>unstrument</code> all the <code>spec/fdef</code> specifications.</p> <pre><code>(def ^:private function-specifications\n  [`card-game/deal-cards\n   `card-game/winning-player])\n</code></pre> <p>Write simple helper functions to wrap the instrumenting of function specifications</p> <pre><code>(defn instrument-all-functions\n  []\n  (spec-test/instrument function-specifications))\n\n(defn unstrument-all-functions\n  []\n  (spec-test/unstrument function-specifications))\n</code></pre>"},{"location":"clojure-spec/organising-specs/#unit-testing","title":"Unit testing","text":"<p>Specifications can be incorporated into the existing unit tests, so it is sensible to keep them under the corresponding <code>test</code> directory files.</p>"},{"location":"clojure-spec/organising-specs/#generative-testing","title":"Generative testing","text":"<p>Using <code>spec-test/check</code> will generate 1000 data values for each expression, so by default these tests will take far longer that other tests.</p> <p>Configuring generative tests to only generate a small number of values will make <code>spec-test/check</code> expressions return almost instantaneously.  In this example, only 10 data values are generated</p> <pre><code>(spec-test/check `deal-cards\n                   {:clojure.spec.test.check/opts {:num-tests 10}})\n</code></pre> <p>Generative testing with small generators can be run regularly during development without impacting fast feedback.</p> <p> Testing with Clojure Spec </p>"},{"location":"clojure-spec/using-spec-in-the-repl/","title":"REPL Experiments with Clojure Spec","text":"Create a minimal Project <p>Clojure Spec can be tried without creating a Clojure project, although creating a project is useful if saving the Clojure Spec code experiments.</p> <p>Create a minimal Clojure project with a Clojure CLI deps.edn configuration. <pre><code>clojure -T:project/create :template practicalli/minimal :name practicalli/spec-experiments\n</code></pre></p> <p>Run a Clojure REPL with a rich terminal UI</p> REPL RebelREPL Reloaded <p>A REPL with a rich terminal UI <pre><code>clojure -M:repl/rebel\n</code></pre></p> <p>A REPL with a rich terminal UI and tools to support the Practicalli REPL Reloaded workflow. <pre><code>clojure -M:repl/reloaded\n</code></pre></p> <p>Require the <code>clojure.spec.alpha</code> using an alias called <code>spec</code> to use functions from that namespace.</p> <pre><code>(require '[clojure.spec.alpha :as spec])\n</code></pre> <p>NOTE: <code>clojure.spec.alpha</code> is often aliased as <code>s</code>, although  Practicalli avoids</p>"},{"location":"clojure-spec/using-spec-in-the-repl/#spec-auto-completion","title":"Spec auto-completion","text":"<p>Using rebel-readline for the Clojure REPL will show autocompletion for all spec functions once the spec namespace has been required.</p> <p>Type <code>(spec /</code> and press <code>TAB</code> to list all the functions in the namespace.</p> <p> </p> <p>Typing a space character after the full name of a function shows the function signature with arguments that should be passed to that function.</p> <p> </p> <p>Ctrl x Ctrl d displays the documentation for the current function </p> <p> </p> <p> </p>"},{"location":"clojure-spec/using-spec-in-the-repl/#check-data-conforms-to-specification","title":"Check data conforms to specification","text":"<p>Use the <code>spec/conform</code> and <code>spec/valid?</code> functions to test if data matches a specification.  In these examples, predicate functions are used as a specification.</p> <p> </p>"},{"location":"clojure-spec/using-spec-in-the-repl/#example-expressions","title":"Example expressions","text":"<p><code>spec/conform</code> will return the value if it conforms to the specification, or <code>:clojure.spec.alpha/invalid</code> if the data does not conform.</p> <p>Clojure Spec - Conform values</p> <pre><code>(spec/conform odd? 101)\n\n(spec/conform integer? 1)\n\n(spec/conform seq? [1 2 3])\n\n(spec/conform seq? (range 10))\n\n(spec/conform map? {})\n\n(spec/conform map? (hash-map :a 1 :b 2))\n</code></pre> <p><code>spec/valid?</code> returns true or false</p> <p>Clojure Spec - validate values</p> <pre><code>(spec/valid? even? 180)\n\n(spec/valid? string? \"Am I a valid string\")\n\n(spec/valid? (fn [value] (&gt; value 10000)) 30076)\n\n(spec/valid? #(&gt; % 10000) 30076)\n\n(spec/conform #(&gt; % 10000) 30076)\n</code></pre>"},{"location":"clojure-spec/data/","title":"Clojure Spec for data","text":"<p>Specifications can be defined for any data in Clojure, be that simple values or complex data structures. More complex specifications are composed of individual specifications, providing a flexible way to define specifications without building a brittle hierarchy.</p>"},{"location":"clojure-spec/data/#what-is-a-specification","title":"What is a specification","text":"<p>Specifications can be predicates (return true or false), literal values in sets and entity maps.</p> <p>There are many predicate functions that come with Clojure which help speed the creation of specifications.  Clojure function definitions (<code>fn</code>, <code>defn</code>) can be used to define custom predicate functions too.</p>"},{"location":"clojure-spec/data/#do-values-meet-a-specification","title":"Do values meet a specification","text":"<p>The functions use to compare data with a specification are:</p> <ul> <li><code>conform</code> - test if data conforms to a specification, returning the conformed value</li> <li><code>valid?</code> - predicate to test if data conforms to a specification, returning true of false</li> <li><code>explain</code> - explain why a value is not conforming to a specification</li> </ul> <p>There are variations on explain, that present the results in different formats.</p>"},{"location":"clojure-spec/data/#workflow-for-data-specifications","title":"Workflow for data specifications","text":"<p>Using Clojure Specification is very flexible, they can be used as much or as little as required.</p> <p>Typically Specifications are created when data structures are being modeled, which can be done via experimenting in the REPL or taking a test first approach.  Either way is viable.</p> <p>The generative tests section shows how specifications are used to generate mock data, so creating specifications earlier on in the development process will provide a wider range of data for unit tests and repl experimentation.</p> <p>Spec and nil values</p> <p>Some predicates do not consider <code>nil</code> as a valid value, espcially those predicates that check for a specific type</p> <p><code>spec/nilable</code> will transform a predicate to use nil</p> <pre><code>(spec/valid? string? nil)\n\n(type \"what type am I\")\n(type nil)\n\n(spec/valid? (spec/nilable string?) nil)\n</code></pre>"},{"location":"clojure-spec/data/and-or-specifications/","title":"Combining specifications with and and or","text":"<p><code>clojure.core/and</code> function and <code>clojure.core/or</code> function can be used to define a specification with multiple parts.</p>"},{"location":"clojure-spec/data/and-or-specifications/#conform-to-one-or-more-specifications","title":"Conform to One or more specifications","text":"<p>A specification for residential address included either a house number or name.  The <code>clojure.core/or</code> function allows either type of value to be used and conform to the specification.</p> <pre><code>(spec/def ::house-name-number (or string? int?))\n</code></pre> <p>Using <code>spec/or</code> then unique keys are required for each possible type of value.  Keys are used to explain where a failure occurred if values do not conform to the specification.</p> <pre><code>(spec/def ::house-name-number (spec/or :string string?\n                                       :number int?))\n</code></pre> <p>If specifications are uses as the options in the <code>clojure.spec.alpha/or</code> then those specification names are used as the keys to explain where failure to conform to the specification happened.</p> <pre><code>(spec/def ::social-security-id (spec/or ::social-security-id-uk\n                                        ::social-security-id-usa))\n</code></pre>"},{"location":"clojure-spec/data/and-or-specifications/#conform-to-all-specifications","title":"Conform to all specifications","text":"<p>Create a composite specification using <code>clojure.spec.alpha/and</code> when all specifications should be conformed by the values</p> <p>For an arranged banking overdraft limit, the value should be a positive number, that is an integer type and is less than 1000.</p> <pre><code>(spec/def ::arranged-overdraft-limit (spec/and pos? int? #(&gt; 1000 %)))\n</code></pre> <p>If a value does not conform to any of the three specifications then the value fails the <code>::arranged-overdraft-limit</code> specification.</p>"},{"location":"clojure-spec/data/composite-specifications/","title":"Composing Specifications","text":"<p>No spec is an island</p> <p>Composing individual specifications is an effective way to build larger abstractions in specifications without creating fixed hierarchical structures that are harder to refactor.</p> <p>Require specification namespace to the page</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p><code>spec/and</code> is used when all specifications should be true.</p> <pre><code>(spec/def ::meaning-of-life\n  (spec/and int?\n            even?\n            #(= 42 %)))\n</code></pre> <p><code>spec/or</code> is use when one or more specifications should be true</p> <pre><code>(spec/def ::meaning-of-life-int-or-string\n  (spec/or :integer #(= 42 %)\n           :string  #(= \"forty two\" %)))\n</code></pre> <p>Each condition in the spec is annotated with a label for each conditional branches.</p> <p>Labels are included in the return result from <code>spec/explain</code> when values do not conform to a specification, providing context as to why a value failed the specification.</p> <p>When an or is conformed, it returns a vector with the condition name and conformed value.</p> <pre><code>(spec/conform ::meaning-of-life-int-or-string 42)\n</code></pre> <pre><code>(spec/conform ::meaning-of-life-int-or-string \"forty two\")\n</code></pre> <pre><code>(spec/conform ::meaning-of-life-int-or-string :entropy)\n</code></pre> <pre><code>(spec/explain ::meaning-of-life-int-or-string :entropy)\n</code></pre>"},{"location":"clojure-spec/data/composite-specifications/#individual-specifications","title":"Individual specifications","text":"<p>Before composing a more abstract specification, first define individual specifications</p> <pre><code>(spec/def ::first-name string?)\n</code></pre> <pre><code>(spec/def ::last-name string?)\n</code></pre> <pre><code>(spec/def ::residential-address string?)\n</code></pre>"},{"location":"clojure-spec/data/composite-specifications/#composing-hash-map-specification","title":"Composing hash-map specification","text":"<p>The individual specifications can now be composed into a single specification.</p> <p><code>keys</code> function combines specifications to form a composite specification in the form of a Clojure hash-map.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::residential-address]))\n</code></pre> <p>Use the composite specification with a value</p> <pre><code>(spec/conform ::customer-details\n  {::first-name \"Jenny\"\n   ::last-name \"Jetpack\"\n   ::residential-address \"42 meaning of life street, Earth\"})\n</code></pre>"},{"location":"clojure-spec/data/conform/","title":"Conform","text":""},{"location":"clojure-spec/data/conform/#does-a-value-conform-to-a-specification","title":"Does a value conform to a specification?","text":"<p><code>clojure.spec.alpha/conform</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>:clojure.spec.alpha/invalid</code> is returned when a value does not conform to a specification.</p> <p>If the value does conform to the specification, then the value is returned.  This value is referred to as a conformed value.</p>"},{"location":"clojure-spec/data/conform/#require-the-clojure-spec-library","title":"Require the Clojure spec library","text":"<p>Set the namespace for the page and require clojure.spec.alpha library, setting the alias to <code>spec</code></p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/conform/#using-conform","title":"Using conform","text":"<p>If the value conforms to the spec, a conformed value is returned</p> <pre><code>(spec/conform odd? 101)\n</code></pre> <p>When a value does not conform to a spec, the value <code>:clojure.spec.alpha/invalid</code> is returned</p> <p><pre><code>(spec/conform even? 101)\n</code></pre> </p> <p><pre><code>(spec/conform integer? 1)\n</code></pre> </p> <p><pre><code>(spec/conform seq? [1 2 3])\n</code></pre> </p> <p><pre><code>(spec/conform seq? (range 10))\n</code></pre> </p> <p><pre><code>(spec/conform map? {})\n</code></pre> </p> <p><pre><code>(spec/conform map? (hash-map :a 1 :b 2))\n</code></pre> </p>"},{"location":"clojure-spec/data/defining-specifications/","title":"Defining specifications","text":"<p><code>clojure.spec.alpha/def</code> binds a name to a specification, just like <code>clojure.core/def</code> binds a name to a value.</p> <p>Binding a name means specifications are available throughout the code and in other projects if the project is included as a library.</p>"},{"location":"clojure-spec/data/defining-specifications/#naming-fully-qualified-keywords","title":"Naming - fully qualified keywords","text":"<p>Specification names should use fully qualified keywords, typically using the namespace in which the specification is defined in.</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <pre><code>(spec/def :practicalli.clojure.specifications/number number?)\n</code></pre>"},{"location":"clojure-spec/data/defining-specifications/#auto-resolve-macro","title":"auto-resolve macro","text":"<p><code>::</code> double colon is the auto-resolve macro, which will pre-pend the current namespace to the specification keyword. The <code>::</code> notation removes the need to edit fully qualified names should a specification be moved to a different namespace.</p> <pre><code>(spec/def ::number number?)\n</code></pre> <p>Fully Qualified keywords</p> <p>Using fully qualified keywords ensures they are unique and therefore can be used across all projects.</p> <p>Namespaces are usually unique as they include the name of the company or organization behind the code and any project or component names used to organize the code.</p>"},{"location":"clojure-spec/data/entity-maps/","title":"Entity maps","text":"<p>An entity map is a Specification for a Clojure hash-map of key-value pairs.</p> <p>A hash-map is a very effective way to express information in Clojure.  The key should be a descriptive label to express meaning of the value it is associated with.  Without the keys describing the meaning, it is harder for a developer to understand the data.</p> <pre><code>{:account-id 12345 :user-name \"jenny1999\" :name \"Jenny Jetpack\" :address \"42 Meaning place, Earth\" :social-security \"ABC-123-45-6789\"}\n</code></pre> <p>A hash-map contains any number of key-value pairs, keys are used for efficient lookup so there is no concern over ordering.  Passing a hash-map as an argument to a function reduces refactoring required as the signature of the function remains the same and functions can be selective as to which key-value pairs they use.</p> <p>For these reasons, hash-maps are a very common data structure to pass data between functions.</p>"},{"location":"clojure-spec/data/entity-maps/#defining-entity-maps","title":"Defining entity maps","text":"<p>The Clojure Spec <code>keys</code> function is used to create a specification for a hash-map of key-value pairs.</p> <p><code>keys</code> creates a specification from required keys, <code>:req</code>, and optional keys <code>:opt</code>.</p> <p>To define the specification for a player in an online game, first the individual specifications that make up the player hash-map are created.</p> <pre><code>(spec/def ::account-id uuid?)\n(spec/def ::name string?)\n(spec/def ::score int?)\n(spec/def ::profile string?)\n(spec/def ::games-played #{:vectron :utrazap :avakato})\n</code></pre> <p>Those specifications are composed together to create a specification for the player</p> <pre><code>(spec/def\n  ::player-account\n  (spec/keys :req [::account-id ::name ::score]\n             :opt [::profile ::games-played]))\n</code></pre> <p>For a hash-map to meet the <code>::player-account</code> specification it must contain the <code>:req</code> keys with values that conform to the individual specifications.  The hash-map can also include any key-value pairs that conform to the <code>:opt</code> specifications.</p> <p>If any keys are in the map that do not appear in either <code>:req</code> or <code>:opt</code> then that hash-map does not conform to the <code>::player-account</code> specification.</p>"},{"location":"clojure-spec/data/entity-maps/#example-covid19-dashboard","title":"Example: covid19-dashboard","text":"<p>The <code>coronavirus-cases-data</code> function takes a hash-map of values to make that function easier to extend without breaking existing calls</p> <p>Default values can be used if no value is passed as an argument. Extra values can be ignored without breaking the code.</p> <p>Coronavirus Cases Specification</p> <pre><code>(defn fun-name\n  [csv location date])\n\n(defn coronavirus-cases-data\n  \"Extract and transform cases data for specific locations and date\"\n  [{:keys [csv-file locations date]}]\n  #_(-&gt; (extract-data-from-csv csv-file)\n        (data-set-remove-locations locations)\n        (data-set-specific-date date)))\n\n(coronavirus-cases-data\n  {:csv-file  \"data-sets/uk-coronavirus-cases.csv\"\n   :locations #{\"Nation\" \"Country\" \"Region\"}\n   :date      \"2020-04-30\"})\n\n;; Define the individual keys for the hash-map\n(spec/def ::csv-file string?)\n(spec/def ::locations set?)\n(spec/def ::date string?)\n\n(spec/def ::cases-data\n  (spec/keys :req [::csv-file ::locations ::date]))\n</code></pre>"},{"location":"clojure-spec/data/explain/","title":"Explaining non-conforming values","text":"<p><code>clojure.spec.alpha/explain</code> describes why a value does not satisfy a specification.</p> <p><code>clojure.spec.alpha/explain</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>Success</code> string is sent to standard out if the value meets the specification</p> <p>A string explaining where the value deviates from the specification is sent to standard out if the value does not meet the specification.</p> <p>There are several variations on the explain function for different situations</p> <ul> <li><code>explain</code> - sends the return value to the standard out / REPL</li> <li><code>explain-str</code> - returns a human readable result.</li> <li><code>explain-data</code> - returns a data structure of the error to be processed by other code</li> </ul>"},{"location":"clojure-spec/data/explain/#example-of-a-failing-value","title":"Example of a failing value","text":"<p>First define a namespace and require the Clojure Spec namespace</p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n\n(spec/def ::meaning-of-life #(= 42 %))\n</code></pre> <p>Given the following specification</p> <pre><code>(spec/explain ::meaning-of-life 24)\n</code></pre> <p>Using the value <code>24</code> with that specification will fail.  Using explain we can see why</p> <pre><code>(spec/def ::meaning-of-life-int-or-string\n  (spec/or :integer #(= 42 %)\n           :string  #(= \"forty two\" %)))\n</code></pre> <p>In this case explain returned the</p> <ul> <li>value being checked against the spec</li> <li>result of that check (failed)</li> <li>predicate used to check the value</li> <li>spec name used to check the value</li> </ul> <p>Notice that the value failed on the first condition, <code>:integer</code>, then stopped without checking the second, <code>:string</code>. The <code>spec/and</code> macro works the same as <code>clojure.core/and</code> in that is stops as soon as something fails.</p> <pre><code>(spec/explain ::meaning-of-life-int-or-string 24)\n</code></pre> <p>In this case we still have the value checked, the result and the predicate More information is provided as to where in the spec the value failed <code>:at</code> shows the path in the spec where the failure occurred, very useful for nested structures This shows the value of naming your specs descriptively</p>"},{"location":"clojure-spec/data/explain/#explain-with-a-string","title":"Explain with a string","text":"<p>rather than send information to the system out</p> <pre><code>(spec/explain-str ::meaning-of-life 24)\n</code></pre> <pre><code>(spec/explain-data ::meaning-of-life 24)\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/","title":"Hierarchical Specifications","text":"<p>Defining specifications for data that is hierarchical or nested in nature.</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#example-hierarchical-data","title":"Example hierarchical data","text":"<pre><code>{:top-level-key {:nested-key \"value\"}}\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#individual-specifications","title":"Individual specifications","text":"<pre><code>(spec/def ::first-name string?)\n</code></pre> <pre><code>(spec/def ::last-name string?)\n</code></pre> <pre><code>(spec/def ::residential-address string?)\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#composite-specification","title":"Composite Specification","text":"<p><code>keys</code> function combines specifications to form a composite specification in the form of a Clojure hash-map.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::residential-address]))\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#hierarchical-specification","title":"Hierarchical Specification","text":"<p>A user account is composed of a user-id and customer details.  Rather than include the individual customer details, the composite customer-details specification.</p> <p>The <code>::user-id</code> specification is as follows</p> <pre><code>(spec/def ::user-id uuid?)\n</code></pre> <p>The <code>::user-account</code> specification</p> <pre><code>(spec/def ::user-account\n  (spec/keys\n    :req [::user-id ::customer-details]))\n</code></pre> <p>The following data structure will conform to the specification</p> <pre><code>{::user-id #uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\"\n ::customer-details {::first-name \"Jenny\"\n                     ::last-name \"Jetpack\"\n                     ::residential-address \"Earth\"}}\n</code></pre>"},{"location":"clojure-spec/data/literal-values/","title":"Literal values","text":"<p>Sets can be used as predicate functions returning true if the value is within the set</p> <p>Checking valid playing cards</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <pre><code>(spec/valid? #{:club :diamond :heart :spade} :club)\n</code></pre> <pre><code>(spec/valid? #{:club :diamond :heart :spade} 42)\n</code></pre> <p>Answer to the ultimate question?</p> <pre><code>(spec/valid? #{42} 42)\n</code></pre> <p>Using sets for literal values is similar to using the <code>clojure.core/contains?</code> function with a set collection type.</p> <pre><code>(contains? #{:clubs :diamonds :hearts :spades} :hearts )\n</code></pre>"},{"location":"clojure-spec/data/map-literals/","title":"Map literal syntax - <code>#:</code> and <code>#::</code>","text":"<p><code>#:</code> map literal macro for Clojure hash-maps adds a given namespace to all the keywords contained in the hash-map.</p> <p><code>#::</code> map literal macro for keyword auto-resolve adds the current fully qualified namespace to all the keywords in the hash-map</p>"},{"location":"clojure-spec/data/map-literals/#require-clojure-spec-in-the-namespace-definition","title":"Require clojure spec in the namespace definition","text":"<pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>In this example the keys in the map are unqualified.</p> <pre><code>{:simplifying      []\n    :keyword-names    []\n    :with-autoresolve []\n    :map-literal      []}\n</code></pre>"},{"location":"clojure-spec/data/map-literals/#qualifying-keys-with-auto-resolve","title":"Qualifying keys with auto-resolve","text":"<p>Using the map literal macro for auto-resolve instructs Clojure to treat all keys in the map as qualified to the current namespace</p> <p>The following hash-map has the map literal macro.</p> <pre><code>#::{:simplifying      []\n    :keyword-names    []\n    :with-autoresolve []\n    :map-literal      []}\n</code></pre> <p>This is the same as explicitly writing out the fully qualified domain for each key in the map.</p> <p>However, if we move the map to another namespace, then the explicit namespaces would need to be updated.</p> <pre><code>{:practicalli.clojure/simplifying      []\n :practicalli.clojure/keyword-names    []\n :practicalli.clojure/with-autoresolve []\n :practicalli.clojure/map-literal      []}\n</code></pre>"},{"location":"clojure-spec/data/map-literals/#qualifying-keywords-with-a-specific-name","title":"Qualifying keywords with a specific name","text":"<p>Rather than take the name from the current namespace, an explicit name can be added to all the keys in the map</p> <pre><code>#:practicalli.naming {:simplifying      []\n                      :keyword-names    []\n                      :with-autoresolve []\n                      :map-literal      []}\n</code></pre> <p>This is the same as explicitly writing that name in front of each of the keywords in the map.</p> <pre><code># {:practicalli.naming/simplifying      []\n   :practicalli.naming/keyword-names    []\n   :practicalli.naming/with-autoresolve []\n   :practicalli.naming/map-literal      []}\n</code></pre> <p>Map literals are relevant to Entity maps with spec.</p>"},{"location":"clojure-spec/data/predicate-functions/","title":"Spec - Predicate functions","text":"<p>A predicate is a function that returns a true or false value and their names end with <code>?</code> by convention.</p> <pre><code>(odd? 1)\n</code></pre> <pre><code>(string? \"am i a string\")\n</code></pre> <pre><code>(int? 2.3)\n</code></pre> <pre><code>(int? 2.3)\n</code></pre> <p><code>clojure.core</code> predicate functions</p> <p><code>clojure.core</code> defines 80+ predicate functions</p>"},{"location":"clojure-spec/data/predicate-functions/#predicate-functions-in-specs","title":"Predicate functions in specs","text":"<p>Predicate functions can be used as un-named specifications to test values conform.</p> <p>Include the <code>clojure.spec.alpha</code> namespace to access the spec functions.</p> <pre><code>(require '[clojure.spec.alpha :as spec])\n</code></pre> <pre><code>(spec/conform int? 42)\n</code></pre> <pre><code>(spec/conform seq? (range 4))\n</code></pre>"},{"location":"clojure-spec/data/predicate-functions/#custom-predicate-functions","title":"Custom predicate functions","text":"<p>Define custom predicate functions with <code>defn</code> or <code>fn</code> or the short form <code>#()</code></p> <p>Using an anonymous function</p> <pre><code>(spec/conform (fn [value] (= value 42)) 42)\n</code></pre> <p>When the expression is quite terse, then the short form of an anonymous function is typically used.  The <code>%</code> represents the value passed as an argument.</p> <pre><code>(spec/conform #(= % 42) 42)\n</code></pre>"},{"location":"clojure-spec/data/registry/","title":"Registry for unique and re-usable specifications","text":"<p>So far we have just use predicate functions directly in the code examples.</p> <p>Using a registry, specs can be uniquely defined across the whole project. Defining a spec gives that spec a name that has a fully qualified namespace</p> <p>Use the spec specific <code>def</code> function to bind a new spec name and fully qualified namespace and place it in the registry</p> <pre><code>(spec/def :playing-card/suit  #{:club :diamond :heart :spade} )\n</code></pre> <pre><code>(spec/conform :playing-card/suit :diamond)\n</code></pre> <pre><code>(spec/def :show-cats/cat-bread #{:abyssinian :birman :chartreau :devon-rex\n                        :domestic-short-hair :domestic-long-hair})\n</code></pre>"},{"location":"clojure-spec/data/registry/#removing-specs-from-the-registry","title":"Removing specs from the registry","text":"<p>Named specifications can be removed from the registry by binding the name to <code>nil</code>.</p> <p>If specification names are to be refactored, then the original name should be set to <code>nil</code> and evaluated, before changing the name.  This will ensure stale specifications are not residing in the REPL.</p> <p>Here is a named specification as an example</p> <pre><code>(spec/def ::unwanted #{:abandoned})\n</code></pre> <p>The specification is evaluated in the REPL (above) and currently works.</p> <pre><code>(spec/conform ::unwanted :abandoned)\n</code></pre> <p>Remove this specification from the registry by binding it to nil</p> <pre><code>(spec/def ::unwanted nil)\n</code></pre> <p>Now the specification is unavailable</p> <pre><code>(spec/conform ::unwanted :abandoned)\n</code></pre> <p>Registry not persistent</p> <p>Restarting the REPL will loose all specification names in the registry as it is not persistent across REPL sessions.</p>"},{"location":"clojure-spec/data/valid-q/","title":"Is the value valid?","text":"<p><code>clojure.spec.alpha/valid?</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>clojure.spec.alpha/valid?</code> is a predicate function.</p> <p><code>true</code> is returned if the value meets the specification, otherwise <code>false</code> is returned.</p>"},{"location":"clojure-spec/data/valid-q/#require-the-clojure-spec-library","title":"Require the Clojure spec library","text":"<p>Set the namespace for the page and require clojure.spec.alpha library, setting the alias to <code>spec</code></p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/valid-q/#using-valid","title":"Using valid?","text":"<p>If the value is valid then a boolean true is returned.  Experiment with different values and predicate functions.</p> <p><pre><code>(spec/valid? even? 180)\n</code></pre> </p> <p><pre><code>(spec/valid? string? \"Am I a valid string\")\n</code></pre> </p>"},{"location":"clojure-spec/data/valid-q/#using-custom-predicate-functions","title":"using custom predicate functions","text":"<p>Create <code>fn</code> definitions to use as predicate functions.  Any function that returns true or false can be used.</p> <pre><code>(spec/valid? (fn [value] (&gt; value 1024)) 8080)\n</code></pre> <p>The custom predicate function may also be written in the shorter form of a <code>fn</code> definition</p> <pre><code>(spec/valid? #(&gt; % 1024) 8080)\n</code></pre> <p>Use <code>def</code> to bind names to custom predicate functions if they are used more than once in the code base.</p> <p>In this example a name is bound to a function that checks if a port is within the range of IANA registered networking ports.</p> <pre><code>(def registered-port-range?\n  \"Network port number within IANA registered port range\"\n  #(and (&gt; % 1024) #(&lt; % 49151) )\n\n(spec/valid? registered-port-range? 8080)\n</code></pre>"},{"location":"clojure-spec/functions/","title":"Specification for function definitions","text":"<p>Define specifications for your custom functions</p> <ul> <li>Additional documentation - argument and return values and the relationship between them.</li> <li>Instrumenting functions - checking for correct argument values</li> <li>Generative testing - using argument specifications to generate comprehensive test data.</li> </ul> <p>Many of the functions in <code>clojure.core</code> have specifications in the latest version of Clojure.  The specifications for clojure.core functions can be found in the clojure/core.specs.alpha repository on GitHub.</p>"},{"location":"clojure-spec/functions/#clojurecore-examples","title":"clojure.core examples","text":"<p>Specifications used for the <code>defn</code>, <code>defn-</code>, <code>fn</code> functions in <code>clojure.core</code></p> <p>clojure.core specification examples</p> <pre><code>(s/def ::param-list\n  (s/and\n    vector?\n    (s/cat :params (s/* ::binding-form)\n           :var-params (s/? (s/cat :ampersand #{'&amp;} :var-form ::binding-form)))))\n\n(s/def ::params+body\n  (s/cat :params ::param-list\n         :body (s/alt :prepost+body (s/cat :prepost map?\n                                           :body (s/+ any?))\n                      :body (s/* any?))))\n\n(s/def ::defn-args\n  (s/cat :fn-name simple-symbol?\n         :docstring (s/? string?)\n         :meta (s/? map?)\n         :fn-tail (s/alt :arity-1 ::params+body\n                         :arity-n (s/cat :bodies (s/+ (s/spec ::params+body))\n                                         :attr-map (s/? map?)))))\n</code></pre>"},{"location":"clojure-spec/functions/documentation/","title":"Documentation","text":"<p>The Clojure <code>doc</code> function shows the doc string included in a function definition, eg. <code>defn</code> expressions.</p> <p>When a specification is defined for a function using <code>fdef</code> the specification is included in the output of the Clojure <code>doc</code> function.</p> <p>Including specification details clarifies the precise way to use the function and the information it expects.  When a function has a specification the doc string for that function can focus on the purpose of the function rather than the specific types of data used, as that is covered by the function specification.</p>"},{"location":"clojure-spec/functions/documentation/#example","title":"Example","text":"<pre><code>(clojure.repl/doc ::rank)\n\n;; :practicalli.card-game-specifications/rank\n;; Spec\n;;   (into #{:king :queen :ace :jack} (range 2 11))\n</code></pre> <p>When adding a specification to a function definition, <code>doc</code> will also show the specification details along with the function doc-string.</p>"},{"location":"clojure-spec/functions/documentation/#live-example","title":"Live example","text":"<p>Define the namespace and include clojure spec and clojure.repl (which contains the doc function)</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.repl :as repl]\n            [clojure.spec.alpha :as spec]))\n</code></pre> <p>Print the documentation for the <code>map</code> function</p> <pre><code>(repl/doc map)\n</code></pre> <p>Print the documentation for the <code>:playing-card/suit</code></p> <pre><code>(clojure.repl/doc :playing-card/suit)\n</code></pre> <pre><code> #{:spade :heart :diamond :club}\n</code></pre> <pre><code>(repl/doc :cat-show:cat-bread)\n</code></pre>"},{"location":"clojure-spec/functions/function-definition-specifications/","title":"Function definition specifications","text":"<p><code>clojure.spec.alpha/fdef</code> defines a specification for a function definition, providing specific specification for</p> <ul> <li>arguments passed when calling a function</li> <li>return value expected</li> <li>relationships between arguments and return value</li> </ul>"},{"location":"clojure-spec/functions/function-definition-specifications/#examples","title":"Examples","text":"<p>The <code>practicalli.database-access/new-account-holder</code> function takes a customer details specification and returns an <code>account-holder-id</code> specification.</p> <p>practicalli.database-access/new-account-holder</p> <pre><code>(spec/fdef practicalli.database-access/new-account-holder\n  :args (spec/cat :customer ::customer-details)\n  :ret ::account-holder-id)\n</code></pre>"},{"location":"clojure-spec/functions/higher-order-functions/","title":"Higher order functions","text":"<p>Higher order functions are common in Clojure and spec provides fspec to support spec\u2019ing them.</p> <pre><code>(defn value-added-tax\n  [tax-rate]\n  #(+ (* tax-rate %) %))\n</code></pre> <p>The value-added-tax function returns an anonymous function that adds the value of tax to the given value.</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>Declare a function spec for value-added-tax using <code>clojure.spec.alpha/fspec</code> for the return value:</p> <pre><code>(s/fdef value-added-tax\n  :args (spec/cat :tax-rate number?)\n  :ret (spec/fspec :args (s/cat :value number?)\n                :ret number?))\n</code></pre> <p>The <code>:ret</code> specification uses <code>fspec</code> to declare that the returning function takes and returns a number.</p>"},{"location":"clojure-spec/generative-testing/","title":"Generative testing with Spec and Spec Test","text":"<p>Clojure spec has been used so far to create specifications for both data and functions.</p> <p>Now spec and spec test libraries are used not just validity checking, but also to generate random samples of the data that can be used for extensive testing.</p> <p>Generative testing provides a far more effective alternative to unit testing.</p> <p><code>clojure.spec.test/check/instrument</code> verifies that calls to a function satisfy the function's specification, the <code>:arg</code> in <code>fdef</code>.</p> <p><code>clojure.spec.test/check</code> function generates 1000 data values to be used as the inputs to a function, checks that the invocation of the function satisfies its specification, the <code>:ret</code> and <code>:fn</code> in <code>fdef</code>.  The argument specification, <code>:arg</code> in <code>fdef</code> is used to generate a wide range of results, which are more capable of finding edge cases that fail.</p> <p> </p>"},{"location":"clojure-spec/generative-testing/#example-card-game","title":"Example: card game","text":"<p>practicalli/spec-generative-testing is a simple card game with specifications that are used for basic generative testing.</p> <p> </p>"},{"location":"clojure-spec/generative-testing/#references","title":"References","text":"<ul> <li>Clojure.org guides: Spec - Generators</li> <li>API reference: clojure.spec.gen.alpha</li> <li>API reference: clojure.spec.test.alpha</li> <li>Video: How to do Stateful Property Testing in Clojure?</li> </ul>"},{"location":"clojure-spec/generative-testing/predicate-generators/","title":"Generators for predicate specifications","text":"<p>Specifications are used to generate a wide range of random data.  A generator for the specification is obtained and then data is generated.</p>"},{"location":"clojure-spec/generative-testing/predicate-generators/#predicate-generators","title":"Predicate generators","text":"<pre><code>(spec-gen/generate (spec/gen int?))\n</code></pre> <pre><code>(spec-gen/generate (spec/gen nil?))\n</code></pre> <pre><code>(spec-gen/sample (spec/gen string?))\n</code></pre> <pre><code>(spec-gen/generate (spec/gen #{:club :diamond :heart :spade}))\n</code></pre> <pre><code>(spec-gen/sample (spec/gen #{:club :diamond :heart :spade}))\n</code></pre>"},{"location":"clojure-spec/generative-testing/example-projects/","title":"Example projects using Clojure Spec","text":"Project How the project uses Spec seancorfield/next-jdbc Data specifications using predicates, function definition argument specifications <p>More examples welcome</p> <p>Other example projects that use interesting features of Spec are most welcome.  Raise an issue on the project issue tracker with details.</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/","title":"Projects using Clojure spec - next-jdbc","text":"<p>The next-jdbc project is a modern low-level Clojure wrapper for JDBC-based access to databases.</p> <p>The project defines data specifications using predicates and</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/#defining-specifications","title":"Defining specifications","text":"<p>Specifications are defined within a single file <code>src/next/jdbc/specs.clj</code>.</p> <p>Specifications start with <code>clojure.spec.alpha/def</code> expressions, using predicate functions as specifications.  There is also a custom predicate function called</p> <p>Function definition specifications follow, using the <code>clojure.spec.alpha/fdef</code> function.  The <code>fdef</code> functions define the specification for the arguments of each function.  The <code>fdef</code> function name is the same as the function definition it is defining a specification for.</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/#instrumenting-specifications","title":"Instrumenting specifications","text":"<p>Instrumenting functions provides automatic checking that argument in a function call conforms to the specification.</p> <p>Rather than write individual expressions to instrument each function, a var called <code>fns-with-specs</code> contains a collection of names for all the <code>fdef</code> function definition specifications.</p> <pre><code>(def ^:private fns-with-specs\n  [`jdbc/get-datasource\n   `jdbc/get-connection\n   `jdbc/prepare\n   `jdbc/plan\n   `jdbc/execute!\n   `jdbc/execute-one!\n   `jdbc/transact\n   `jdbc/with-transaction\n   `connection/-&gt;pool\n   `prepare/execute-batch!\n   `prepare/set-parameters\n   `prepare/statement\n   `sql/insert!\n   `sql/insert-multi!\n   `sql/query\n   `sql/find-by-keys\n   `sql/get-by-id\n   `sql/update!\n   `sql/delete!])\n</code></pre> <p>Instrument all the functions by passing <code>fns-with-specs</code> as an argument to the <code>clojure.spec.test.alpha/instrument</code> function.</p> <p>This call is wrapped in a simple handler function for convenience.</p> <pre><code>(defn instrument []\n  (clojure.spec.test.alpha/instrument fns-with-specs))\n</code></pre> <p>To remove the checking of argument specifications, <code>clojure.spec.test.alpha/unstrument</code> is passed <code>fns-with-specs</code>, again wrapped in a convinced function.</p> <pre><code>(defn unstrument []\n  (clojure.spec.test.alpha/unstrument fns-with-specs))\n</code></pre>"},{"location":"clojure-spec/projects/","title":"Clojure Spec Projects","text":"<p>A series of projects showing approaches to using specifications and generating data for testing.</p> Project Description card game writing specifications and generating data from those specifications banking-on-clojure simplified online bank account using TDD, data and functional specifications and generative testing Bonbon card game A flavorful card game with clojure spec Genetic Programming With clojure.spec https://www.youtube.com/watch?v=xvk-Gnydn54 ClojureScript game with spec"},{"location":"clojure-spec/projects/#references","title":"References","text":"<ul> <li>Practicalli - Clojure Spec playlist - live coding to define specifications and generative testing</li> </ul>"},{"location":"clojure-spec/projects/bank-account/","title":"Spec project: Bank Account","text":"<p>A relatively simple bank account application with data and function specifications, including generative testing data and function instrumentation.</p>"},{"location":"clojure-spec/projects/bank-account/#hintunder-active-development","title":"Hint::Under active development","text":"<p>Developed as part of the Practicalli study guide live broadcasts</p>"},{"location":"clojure-spec/projects/bank-account/#create-depsedn-project","title":"Create deps.edn project","text":"<p>Use Clojure CLI and <code>clj-new</code></p> <pre><code>clojure -M:new app practicalli/banking-on-clojure\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/#hintpracticallibanking-on-clojure-repository","title":"Hint::practicalli/banking-on-clojure repository","text":"<p>practicalli/banking-on-clojure repository contains the latest code to date for this project.</p>"},{"location":"clojure-spec/projects/bank-account/#outline-design-of-project","title":"Outline design of project","text":"<p>Data Specifications are created for</p> <ul> <li>Customer Details \u2714</li> <li>Account holder \u2714</li> <li>Bank account</li> <li>Multiple Bank accounts</li> <li>Credit Card</li> <li>Mortgage</li> </ul> <p>Functions and specifications are created for</p> <ul> <li>register-account-holder \u2714</li> <li>open-credit-account</li> <li>open-savings-account</li> <li>open-credit-card-account</li> <li>open-mortgage-account</li> <li>Make a payment</li> <li>Send account notification</li> <li>Check for overdraft</li> </ul>"},{"location":"clojure-spec/projects/bank-account/#development-workflow","title":"Development Workflow","text":"<ul> <li>Write a failing test \u2714</li> <li>write mock data \u2714</li> <li>write an function definition that returns the argument \u2714</li> <li>run tests - tests should fail \u2714</li> <li>write a spec for the functions argument - customer \u2714</li> <li>write a spec for the return value \u2714</li> <li>write a spec for relationship between args and return value</li> <li>replace the mock data with generated values from specification \u2714</li> <li>update functions and make tests pass \u2714</li> <li>instrument functions</li> <li>run specification checks</li> </ul> <p>\u2714</p> <p>Images to add</p> <p>Running tests that fail on a spec in CIDER spacemacs-cider-test-spec-fail-banking-on-clojure-project.png</p> <p>Running tests that fail on a spec on CircleCI circle-ci-banking-on-clojure-spec-test-runner-fail-register-account-holder-did-not-conform-to-spec.png</p>"},{"location":"clojure-spec/projects/bank-account/account-holder-specification/","title":"Account holder specification","text":"<p>The account holder has the same information as custom details with the addition of an account-id</p> <p>In the register-account-holder a uuid is generated for the account id, So a spec can be defined for this type</p> <pre><code>(spec/def ::account-id uuid?)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/account-holder-specification/#design-decision-hierarchical-or-composite","title":"Design decision: hierarchical or composite","text":"<p>There are several approaches to combining, depending on the shape of the data used</p> <p>The account holder is a hash-map, so <code>spec/keys</code> will create the map from specification keys</p> <p>Including the customer-details specification in <code>spec/keys</code> would include the customer details as a nested hash-map</p> <pre><code>(spec/def ::account-holder-hierarchy\n  (spec/keys\n    :req [::account-id ::customer-details]))\n</code></pre> <p>A valid data structure for this specification is a map with two keys, <code>account-id</code> and <code>customer-details</code>. <code>account-id</code> is a uuid value, customer-details is a hash-map of values that conform to the customer-details specification</p> <pre><code>(spec/valid? ::account-holder-hierarchy\n             #::{:account-id       (java.util.UUID/randomUUID)\n                 :customer-details #:: {:first-name          \"Jenny\"\n                                        :last-name           \"Jetpack\"\n                                        :email-address       \"jenny@jetpack.org\"\n                                        :residential-address \"42 meaning of life street, Earth\"\n                                        :postal-code         \"AB3 0EF\"\n                                        :social-security-id  \"123456789\"}})\n;; =&gt; true\n</code></pre> <p>Flat data structures are usually preferred in Clojure over a nested hierarchy. Rather than use the ::customer-details specification as a key in the <code>spec/keys</code> expression. The individual specifications that make up ::customer-details can be used.</p> <pre><code>(spec/def ::account-holder-composition\n  (spec/keys\n    :req [::account-id ::first-name ::last-name ::email-address ::residential-address ::social-security-id]))\n</code></pre> <pre><code>(spec/valid? ::account-holder-composition\n             #::{:account-id          (java.util.UUID/randomUUID)\n                 :first-name          \"Jenny\"\n                 :last-name           \"Jetpack\"\n                 :email-address       \"jenny@jetpack.org\"\n                 :residential-address \"42 meaning of life street, Earth\"\n                 :postal-code         \"AB3 0EF\"\n                 :social-security-id  \"123456789\"})\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/","title":"Customer details specification","text":"<p>Create a new file for the specifications, <code>src/practicalli/banking_specifications.cljc</code>, with the namespace <code>practicalli.banking-specifications</code>.</p> <p>Require the <code>clojure.spec.alpha</code> library with an alias of <code>spec</code>.</p> <pre><code>(ns practicalli.banking-specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#define-basic-customer-details","title":"Define basic customer details","text":"<p>Define a specification for the customer-details map, composed of all the required keys that define a customer.</p> <p>The bank legally requires specific information about a customer in order to add them as an account holder</p> <pre><code>(spec/def ::first-name string?)\n(spec/def ::last-name string?)\n(spec/def ::email-address string?)\n</code></pre> <pre><code>(spec/def ::email-address\n  (spec/and string?\n            #(re-matches #\"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,63}$\"\n                         %)))\n</code></pre> <p>This specification will require a custom generator</p> <p>A residential address is made from several pieces of information and is defined as a composite specification, from several specifications.</p> <pre><code>(spec/def ::house-name-number (spec/or :string string?\n                                       :number int?))\n(spec/def ::street-name string?)\n(spec/def ::post-code string?)\n(spec/def ::county string?)\n(spec/def ::country string?)\n</code></pre> <pre><code>(spec/def ::residential-address (spec/keys :req [::house-name-number ::street-name ::post-code]\n                                           :opt [::county ::country]))\n</code></pre> <p>A social security number specification is also a candidate for a composite specification. Social security numbers may take different forms and even have different names in different countries, eg. the USA SSN is a nine-digit number in the format \"AAA-GG-SSSS\"</p> <p>In the UK the social security number is called the National Insurance number and is of the form QQ123456C</p> <pre><code>(spec/def ::social-security-id-uk string?)\n(spec/def ::social-security-id-usa string?)\n</code></pre> <pre><code>(defn social-security-number-usa? [value] (= 9 (count value)))\n(defn social-security-number-uk? [value] (= 11 (count value)))\n(spec/def ::social-security-id-usa (spec/and string? social-security-number-usa?))\n(spec/def ::social-security-id-uk (spec/and string? social-security-number-uk?))\n</code></pre> <p>These specifications required a custom generator in order to produce correct data each time.</p> <p>A general social security specification can now be defined, with one of any of the country specific specifications</p> <pre><code>(spec/def ::social-security-id (spec/or ::social-security-id-uk\n                                        ::social-security-id-usa))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#infoa-more-detailed-email-specification","title":"INFO::A more detailed email specification","text":"<p>Use a regular expression to define the syntax of an email address, eg. jenny@jetpack.org</p>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#infodetailed-social-security-numbers-would-check-the-different-forms","title":"INFO::Detailed social security numbers would check the different forms","text":"<p>Predicate functions can be defined to check for the size of the different social security forms.</p>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#composing-the-customer-details-specification","title":"Composing the customer details specification","text":"<p>A customer details specification is a hash-map of key value pairs. The keys are the specifications that have just been defined.</p> <p><code>spec/keys</code> creates a specification for a hash-map with required and optional keys.  <code>spec/keys</code> also includes a check for a map, so no explicit check for a map is required.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::email-address ::residential-address ::social-security-id]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/","title":"Specifications for function definitions - <code>fdef</code>","text":"<p>Create a <code>spec/fdef</code> for the register-account-holder function</p> <p><code>clojure.spec.alpha/fdef</code> defines a specification for a function definition, <code>defn</code>. Specifications can attached to the arguments using <code>:args</code>, the return value using <code>:ret</code> and the relationship between the two using <code>fn</code>.</p> <p><code>:args</code>, <code>:ret</code> and <code>fn</code> are optional, although <code>args</code> and <code>ret</code> are required if you want to use <code>:fn</code></p>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#add-a-spec-to-cover-the-function-arguments","title":"Add a spec to cover the function arguments","text":"<p><code>:args</code> is a compound specification that covers all the function arguments. The <code>:args</code> spec is invoked with the arguments in a list, so working with them is like using apply.</p> <p>Using regular expressions we can find the right arguments to give to the specification. Regular expression spec functions include</p> <ul> <li><code>spec/cat</code></li> <li><code>spec/alt</code></li> <li><code>spec/*</code></li> </ul> <p>The register-account-holder only takes one argument, so <code>spec/cat</code> is used to bind a local key to the specification.</p> <p>The function is defined in the <code>practicalli.banking-on-clojure</code> namespace.  Require that namespace in the current <code>ns</code> form.</p> <pre><code>(ns practicalli.banking-specifications\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]\n\n            [practicalli.banking-on-clojure :as SUT]))\n</code></pre> <p>The <code>SUT</code> alias is used for the banking-on-clojure namespace, as is done with <code>clojure.test</code> unit test namespaces.</p> <pre><code>(spec/fdef SUT/register-account-holder\n  :args (spec/cat :customer\n                  :practicalli.bank-account-spec/customer-details))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#checking-function-calls-against-the-spec-instrument","title":"Checking function calls against the spec - instrument","text":"<p><code>spec/fdef</code> by itself does not run checks against the specs</p> <pre><code>(register-account-holder {})\n;; =&gt; {:account-id #uuid \"3a6dddb7-dd87-485e-90f8-8c8975302845\"}\n</code></pre> <p>Require the Clojure spec test library</p> <pre><code>(require '[clojure.spec.test.alpha :as spec-test])\n</code></pre> <p><code>spec/instrument</code> will add a run time check for the specification</p> <pre><code>(spec-test/instrument `SUT/register-account-holder)\n</code></pre> <p>No the function is instrumented, data used as arguments of a function call will be checked against the specification.</p> <pre><code>(register-account-holder {::bad \"data\"})\n</code></pre> <p>This function call throws an exception because of the specification attached to the <code>:args</code> section of the <code>fdef</code> specification.</p> <p>The error report provides detailed and quite clear information to help diagnose the issue</p> <pre><code> 1. Unhandled clojure.lang.ExceptionInfo\n Spec assertion failed.\n\n Spec: #object[clojure.spec.alpha$regex_spec_impl$reify__2509 0x12b66a86 \"clojure.spec.alpha$regex_spec_impl$reify__2509@12b66a86\"]\n Value: (#:practicalli.bank-account-design-journal{:bad \"data\"})\n\n Problems:\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/first-name)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/last-name)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/email-address)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/residential-address)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/social-security-id)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n</code></pre> <p>Calling the register-account-holder with a value that conforms to the bank-account-spec for customer details returns the new value for account-holder</p> <pre><code>(register-account-holder\n  #:practicalli.bank-account-spec\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n\n;; =&gt; {:practicalli.bank-account-spec/first-name \"Jenny\", :practicalli.bank-account-spec/last-name \"Jetpack\", :practicalli.bank-account-spec/email-address \"jenny@jetpack.org\", :practicalli.bank-account-spec/residential-address \"42 meaning of life street, Earth\", :practicalli.bank-account-spec/postal-code \"AB3 0EF\", :practicalli.bank-account-spec/social-security-id \"123456789\", :account-id #uuid \"e0f327de-4e92-479e-a9de-468e2c7c0e6d\"}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#add-a-specification-to-the-return-value","title":"Add a specification to the return value","text":"<p>Attach the account-holder details specification to <code>:ret</code></p> <pre><code>(spec/fdef register-account-holder\n  :args (spec/cat :customer\n                  :practicalli.bank-account-spec/customer-details)\n  :ret :practicalli.bank-account-spec/account-holder)\n</code></pre> <p>If the <code>register-account-holder</code> logic changes to return a different value that the return spec, then an exception is raised</p> <p>Returns an integer rather than a uuid</p> <pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n  [customer-details]\n\n  (assoc customer-details\n         :practicalli.bank-account-spec/account-id\n         (rand-int 100000)\n         #_(java.util.UUID/randomUUID)))\n</code></pre> <p>So this should fail</p> <pre><code>(register-account-holder\n  #:practicalli.bank-account-spec\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <p>It still works as <code>spec-test/instrument</code> only checks the args value.</p> <p><code>spec-test/check</code> will test the return value with generated tests</p> <pre><code>(require '[clojure.spec.gen.alpha :as spec-gen])\n</code></pre> <pre><code>(spec-test/check `SUT/register-account-holder)\n</code></pre> <p>The result is 100 generated tests that all fail, because the function was changed to return integers, not uuids</p> <pre><code> 1. Caused by clojure.lang.ExceptionInfo\n Couldn't satisfy such-that predicate after 100 tries.\n {:pred      #function[clojure.spec.alpha/gensub/fn--1876],\n  :gen       {:gen #function[clojure.test.check.generators/such-that/fn--8322]},\n  :max-tries 100}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#change-the-function-back-again","title":"Change the function back again","text":"<pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n  [customer-details]\n\n  (assoc customer-details\n         :practicalli.bank-account-spec/account-id\n         (java.util.UUID/randomUUID)))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#instrument-the-function","title":"Instrument the function","text":"<p>Testing function calls against the specification</p> <p>Requires the spec test namespace</p> <pre><code>(require '[clojure.spec.test.alpha :as spec-test])\n</code></pre> <p>Instrument the spec to add checking, this only checks the arguments are correct.</p> <pre><code>(spec-test/instrument `practicalli.bank-account/register-account-holder)\n</code></pre> <pre><code>(register-account-holder {:first-name          \"Jenny\"\n                          :last-name           \"Jetpack\"\n                          :email-address       \"jenny@jetpack.org\"\n                          :residential-address \"42 meaning of life street\"\n                          :postal-code         \"AB3 0EF\"\n                          :social-security-id  \"123456789\"})\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/","title":"Generate test data","text":""},{"location":"clojure-spec/projects/bank-account/generate-test-data/#generate-test-data-from-specifications","title":"Generate test data from Specifications","text":"<p>Now there are specifications for the customer-details and account-details, spec can generate random data for use with tests.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#add-requires-to-the-test-namespace","title":"Add requires to the test namespace","text":"<p>Edit the <code>src/test/practicalli/banking_on_clojure.clj</code> and add requires for the <code>banking-specifications</code>, <code>clojure.spec.alpha</code> and <code>clojure.spec.test.alpha</code>.</p> <pre><code>(ns practicalli.banking-on-clojure-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [clojure.spec.alpha :as spec]\n            [clojure.spec.test.alpha :as spec-test]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [practicalli.banking-on-clojure :as SUT]\n            [practicalli.banking-specifications]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#using-generators-to-generate-data","title":"Using Generators to generate data","text":"<p>Test data can now be generated from this specification, creating values for each key in the hash-map.</p> <p>The ::email-address specification has been simplified, as the regular expression version requires a custom generator (no built in generator to support this specification).  The simplified email specification is:</p> <pre><code>(spec/def ::email-address string?)\n</code></pre> <p>With the simplified email specification, the customer-details specification can be used to generate all the data using the built in clojure.spec.alpha generators.</p> <pre><code>(spec-gen/generate (spec/gen :practicalli.banking-specifications/customer-details))\n\n;; =&gt; #:practicalli.banking-specifications\n{:first-name \"r7q9RFB202v7a69z\",\n :last-name \"6N5\",\n :email-address \"L6dd946p680P0pIYZ33CGZd0\",\n :residential-address\n   #:practicalli.banking-specifications{\n      :house-name-number \"gCuRMe0C8\",\n      :street-name \"5\",\n      :post-code \"VN\"},\n      :social-security-id \"a7P0xfBNPv6\"}\n</code></pre> <p>Bind the result of this function to a name and it can be used as mock data throughout the unit tests defined.</p> <pre><code>(defn customer-details-mock-data\n  (spec-gen/generate (spec/gen :practicalli.banking-specifications/customer-details)))\n</code></pre> <p>The generated data can also be used with function definitions and <code>clojure.spec.test.alpha/check</code> function.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#hintlibraries-for-custom-generators","title":"Hint::Libraries for custom generators","text":"<p>gfredericks/test.chuck is a utility library for test.check and will work with clojure spec as its a wrapper around test.check.</p> <p>lambdaisland/regal also has test.check generators that can be used for regular expressions defined with the regal (hiccup style) syntax.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#generating-more-than-one-value-for-a-specification","title":"Generating more than one value for a specification","text":"<p><code>clojure.spec.gen.alpha/sample</code> will generate 10 random values from the specification</p> <pre><code>(spec-gen/sample (spec/gen :practicalli.banking-specifications/customer-details))\n\n;; =&gt; (#:practicalli.banking-specifications{:first-name \"\", :last-name \"\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:country \"\", :county \"\", :house-name-number \"\", :street-name \"\", :post-code \"\"}, :social-security-id \"2P902qTJCP6\"}\n\n#:practicalli.banking-specifications{:first-name \"\", :last-name \"z\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:house-name-number 0, :street-name \"\", :post-code \"R\"}, :social-security-id \"3dDBA7pa98r\"}\n\n#:practicalli.banking-specifications{:first-name \"nQ\", :last-name \"w\", :email-address \"h6\", :residential-address #:practicalli.banking-specifications{:country \"\", :county \"7u\", :house-name-number \"\", :street-name \"87\", :post-code \"\"}, :social-security-id \"x57pf2H2i16\"}\n\n#:practicalli.banking-specifications{:first-name \"ac\", :last-name \"L0x\", :email-address \"S\", :residential-address #:practicalli.banking-specifications{:country \"Xd\", :county \"\", :house-name-number \"P\", :street-name \"\", :post-code \"\"}, :social-security-id \"j5iTA70j9FW\"}\n\n#:practicalli.banking-specifications{:first-name \"e\", :last-name \"ic\", :email-address \"15G\", :residential-address #:practicalli.banking-specifications{:house-name-number \"\", :street-name \"Nj\", :post-code \"f\"}, :social-security-id \"I83rx1wUj07\"}\n\n#:practicalli.banking-specifications{:first-name \"zPr\", :last-name \"r\", :email-address \"hsVz\", :residential-address #:practicalli.banking-specifications{:country \"W\", :house-name-number \"S\", :street-name \"64\", :post-code \"85s25\"}, :social-security-id \"8EEDiy28SX7\"}\n\n#:practicalli.banking-specifications{:first-name \"QzoV\", :last-name \"\", :email-address \"iS\", :residential-address #:practicalli.banking-specifications{:county \"OaMj9\", :house-name-number 1, :street-name \"pzc0ji\", :post-code \"tv1\"}, :social-security-id \"9z88KM5TLKK\"}\n\n#:practicalli.banking-specifications{:first-name \"w73AA\", :last-name \"\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:county \"sUj\", :house-name-number 4, :street-name \"jw\", :post-code \"652Z\"}, :social-security-id \"rZMUTPK72N6\"}\n\n#:practicalli.banking-specifications{:first-name \"j09f\", :last-name \"EoU\", :email-address \"sA82q\", :residential-address #:practicalli.banking-specifications{:country \"28nyq3\", :county \"5PURE\", :house-name-number \"1NzKwe\", :street-name \"28Y\", :post-code \"t\"}, :social-security-id \"yNBdc7M29Io\"}\n\n#:practicalli.banking-specifications{:first-name \"Xa38iX8FP\", :last-name \"u4G\", :email-address \"Ne1w25nJ\", :residential-address #:practicalli.banking-specifications{:country \"H07\", :house-name-number -17, :street-name \"jWRhfrrz9\", :post-code \"sF9\"}, :social-security-id \"IX2w8Xx8u0n\"})\n</code></pre> <p>Generating multiple result is useful if a collection of customer details is required for testing purposes.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#exercising-a-specification","title":"Exercising a specification","text":"<p><code>clojure.spec.test.alpha/exercise</code> returns pairs of generated and conformed values for a spec. exercise by default produces 10 samples (like sample) but you can pass both functions a number indicating the number of samples to produce.</p> <pre><code>(spec/exercise (spec/cat :practicalli.banking-specifications/first-name :practicalli.banking-specifications/last-name))\n\n;; =&gt; ([(\"\") #:practicalli.banking-specifications{:first-name \"\"}]\n       [(\"6\") #:practicalli.banking-specifications{:first-name \"6\"}]\n       [(\"\") #:practicalli.banking-specifications{:first-name \"\"}]\n       [(\"6\") #:practicalli.banking-specifications{:first-name \"6\"}]\n       [(\"W\") #:practicalli.banking-specifications{:first-name \"W\"}]\n       [(\"ljooD\") #:practicalli.banking-specifications{:first-name \"ljooD\"}]\n       [(\"704d5x\") #:practicalli.banking-specifications{:first-name \"704d5x\"}]\n       [(\"EZyBT\") #:practicalli.banking-specifications{:first-name \"EZyBT\"}]\n       [(\"1e6\") #:practicalli.banking-specifications{:first-name \"1e6\"}]\n       [(\"v\") #:practicalli.banking-specifications{:first-name \"v\"}])\n</code></pre> <p><code>clojure.spec.test.alpha/exercise-fn</code> provides the same service but for function specifications (<code>fdef</code>).</p>"},{"location":"clojure-spec/projects/bank-account/rebel-readline/","title":"Using the project in rebel readline","text":"<p>Start the rebel REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Once rebel has started a prompt will be displayed.</p> <p>First required the main namespace, containing the functions of the application.  This loads the code in that namespace into the REPL.</p> <pre><code>(require 'practicalli.banking-on-clojure)\n</code></pre> <p>Now add the specifications for the project</p> <pre><code>(require 'practicalli.banking-on-clojure)\n</code></pre> <p>? When does the TAB completion start to work ?</p> <p>Testing the specifications</p> <p>First change into the specifications namespace so the fully qualified names of the specs are not required.</p> <pre><code>(in-ns 'practicalli.banking-specifications)\n</code></pre> <p>Generate sample data from the specifications</p> <pre><code>(spec-gen/sample (spec/gen ::account-id))\n</code></pre> <p>The function specifications and the instrument functions are loaded from the requires, so test by calling the instrumented functions, first with bad data and then with correct data.</p> <pre><code>(register-account-holder {})\n</code></pre> <p>Use the specifications to generate good data</p> <pre><code>(register-account-holder ::customer-details)\n</code></pre> <p>Run generative tests on functions to check the return and fn values</p> <pre><code>(spec-test/check `register-account-holder)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/rebel-readline/#hinttodo-add-screenshots-using-rebel-readline-repl","title":"Hint::TODO: add screenshots using Rebel readline REPL","text":""},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/","title":"Test functions against spec","text":""},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#generative-testing-with-check","title":"Generative testing with <code>check</code>","text":"<p><code>clojure.spec.test.alpha/check</code> generates 1000 values from the argument section of a function definition specification.</p> <p>Pass the name of the function definition that has a specification to the <code>check</code> function.</p> <pre><code>(spec-test/check ``register-account-holder`)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#limiting-the-generated-data","title":"Limiting the generated data","text":"<p>1000 tests can take a noticeable time to run, so check is not as often used during active development, as it would slow down the normal fast feedback cycle with Clojure.</p> <p><code>check</code> takes an optional second argument which configures how the function operates.  Passing a hash-map as a second argument will set the number of data values generated <code>{:clojure.spec.test.check/opts {:num-tests 100}}</code></p> <pre><code>(spec-test/check\n  `register-account-holder\n  {:clojure.spec.test.check/opts {:num-tests 100}})\n</code></pre> <p>Configuring <code>check</code> to run fewer tests provides a simple way to test multiple values without slowing down the development workflow.</p>"},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#reporting-on-generative-testing","title":"Reporting on Generative testing","text":"<p><code>clojure.spec.test.alpha/summarize-results</code> will return a brief summary including the total number of results and a count for how many results passed and failed.</p> <pre><code>(spec-test/summarize-results\n  (spec-test/check `register-customer\n                   {:clojure.spec.test.check/opts {:num-tests 10}}))\n</code></pre> <p>Use the threading macro to summarize the results of multiple check operations</p> <pre><code>(-&gt;&gt; (spec-test/check `register-account-holder)\n     (spec-test/check `open-current-bank-account)\n     (spec-test/summarize-results))\n</code></pre> <p>If this expression is bound to a name then it can be called when ever the full suite of <code>check</code> generative testing is required.</p>"},{"location":"clojure-spec/projects/bank-account/unit-tests-with-spec/","title":"Unit tests with specs","text":"<p>Now that customer data and account-holder data has a specification, we can use the <code>clojure.spec.alpha/valid?</code> in the unity test code, as that function returns true or false.</p> <p>In this example the result of a call to <code>register-account-holder</code> is checked to see if it is valid against the <code>::account-holder</code> specification.  This simplifies the code needed in unit test assertions, as Clojure spec is doing the work.</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (SUT/register-account-holder customer-mock)))\n           (set (keys account-holder))))\n\n    (is (spec/valid? :practicalli.bank-account-spec/account-holder\n                     (SUT/register-account-holder customer-mock) ) )\n    ))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/","title":"Testing data Specifications","text":"<p>The specifications defined so far can be tested with specific data, using the <code>conform</code> or <code>valid?</code> functions.</p> <p>Generating sample data from the specifications also provides useful feedback on how well the specifications are defined.</p>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#generating-data-from-specifications","title":"Generating data from specifications","text":"<p>Test data specifications by generating sample data from those specifications.</p> <p>Evaluating these functions several times is a quick way to identifies specifications that may require custom generators. If individual specifications do not generate consistent data, then incorrect results may occur during composite data specifications or function specifications.</p> <pre><code>(spec-gen/sample (spec/gen ::first-name))\n(spec-gen/sample (spec/gen ::last-name))\n(spec-gen/sample (spec/gen ::email-address))\n(spec-gen/sample (spec/gen ::house-name-number))\n(spec-gen/sample (spec/gen ::street-name))\n(spec-gen/sample (spec/gen ::post-code))\n(spec-gen/sample (spec/gen ::county))\n(spec-gen/sample (spec/gen ::country))\n(spec-gen/sample (spec/gen ::residential-address))\n(spec-gen/sample (spec/gen ::social-security-id-uk))\n(spec-gen/sample (spec/gen ::social-security-id-usa))\n(spec-gen/sample (spec/gen ::social-security-id))\n(spec-gen/sample (spec/gen ::customer-details))\n(spec-gen/sample (spec/gen ::account-holder))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#validating-the-customer-details-specifications","title":"Validating the customer details specifications","text":"<p>The specifications can be checked using the conform or valid? functions with example data.</p> <p>Check an example hash-map from our test conforms to the specification</p> <pre><code>(spec/conform ::customer-details\n              {:first-name          \"Jenny\"\n               :last-name           \"Jetpack\"\n               :email-address       \"jenny@jetpack.org\"\n               :residential-address \"42 meaning of life street\"\n               :postal-code         \"AB3 0EF\"\n               :social-security-id  \"123456789\"})\n;; =&gt; :clojure.spec.alpha/invalid\n</code></pre> <p>The mock test data does not confirm to the specification, even though it has all the same keys as the map in the specification</p> <pre><code>(spec/valid? ::customer-details\n             {:first-name          \"Jenny\"\n              :last-name           \"Jetpack\"\n              :email-address       \"jenny@jetpack.org\"\n              :residential-address \"42 meaning of life street\"\n              :postal-code         \"AB3 0EF\"\n              :social-security-id  \"123456789\"})\n;; =&gt; false\n</code></pre> <p><code>spec/explain</code> will provide more information to help diagnose the issue</p> <pre><code>(spec/explain ::customer-details\n              {:first-name          \"Jenny\"\n               :last-name           \"Jetpack\"\n               :email-address       \"jenny@jetpack.org\"\n               :residential-address \"42 meaning of life street\"\n               :postal-code         \"AB3 0EF\"\n               :social-security-id  \"123456789\"})\n\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/first-name) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/last-name) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/email-address) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/residential-address) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/social-security-id) spec: :practicalli.bank-account-design-journal/customer-details\n</code></pre> <p>The <code>::customer-details</code> spec is given a map with unqualified keys and is failing the <code>:req</code> part of the <code>spec/keys</code> part of the specification</p>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#qualifying-keys-with-auto-resolve-macro","title":"Qualifying keys with auto-resolve macro","text":"<p>The auto-resolve macro, <code>#::</code> will add the current namespace to all the keys in a hash-map</p> <p>Change the test data to use qualified keys by adding the</p> <pre><code>(spec/conform ::customer-details\n              #::{:first-name          \"Jenny\"\n                  :last-name           \"Jetpack\"\n                  :email-address       \"jenny@jetpack.org\"\n                  :residential-address \"42 meaning of life street\"\n                  :postal-code         \"AB3 0EF\"\n                  :social-security-id  \"123456789\"}  )\n;; =&gt; #:practicalli.bank-account-design-journal{:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/","title":"Write failing tests","text":"<p>In Test Driven Development style, first write unit tests for the banking functions.</p> <p>Edit the <code>src/practicalli/banking_on_clojure_test.clj</code> and add <code>deftest</code> tests</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (register-account-holder {})))\n           (set (keys {:account-id \"123\" :customer-name \"Jenny Jetpack\"}))))))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/#write-a-function-stub-to-run-the-tests","title":"Write a function stub to run the tests","text":"<p>The tests cannot run unless they call the function to be tested.  A common approach it to write a function that returns the argument.</p> <pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n\n  [customer-details]\n\n  customer-details)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/#add-mock-data","title":"Add mock data","text":"<p>Define some initial mock data to use with the unit tests</p> <pre><code>(def customer-mock\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <pre><code>account is a customer with a bank account id added\n\n(def account-holder-mock\n  {:account-id           #uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\"\n   :first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <p>Update the test to use the mock data.</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (register-account-holder customer-mock)))\n           (set (keys account-holder-mock))))))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/","title":"Card game: spec and generative testing","text":"<p>Define a data specification that represent a deck of playing cards, adding functional specifictations to check the values passed to the functions use to play a card game.</p> <p>spec generators are used to return varied sample data from those specifications. Function definitions are instrumented and check for correct arguments when those functions are called.</p>"},{"location":"clojure-spec/projects/card-game/#create-a-new-project","title":"Create a new project","text":"<p>Create a new Clojure project using <code>:project/create</code> from  Practicalli Clojure CLI Config or add an alias definition of your choosing to the Clojure CLI user configuration.</p> <pre><code>clojure -T:project/create :template app :name practicalli/card-game\n</code></pre> <p>Open the <code>src/practicalli/card_game.clj</code> file and require the <code>clojure.spec.alpha</code> namespace</p> <pre><code>(ns practicalli.card-game.clj\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#playing-card-specifications","title":"Playing card specifications","text":"<p>A playing card has a face value and a suit. There are 4 suits in a card deck.</p> <p>A specification for the possible suits can be defined using literal values</p> <pre><code>(spec/def ::suits #{:clubs :diamonds :hearts :spades})\n</code></pre> <p>Define a predicate function to check a value conforms to the spec using the pattern matching that is build-in to the Clojure <code>set</code> data type.</p> <pre><code>(def suits? #{:clubs :diamonds :hearts :spades})\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#card-game-decks","title":"Card game decks","text":"<p>Suits from different regions are called by different names.  Each of these suits can be their own spec.</p> <pre><code>(spec/def ::suits-french #{:hearts :tiles :clovers :pikes})\n(spec/def ::suits-german #{:hearts :bells :acorns :leaves})\n(spec/def ::suits-spanish #{:cups :coins :clubs :swords})\n(spec/def ::suits-italian #{:cups :coins :clubs :swords})\n(spec/def ::suits-swiss-german #{:roses :bells :acorns :shields})\n</code></pre> <p>A composite specification called <code>::card-suits</code> provides a simple abstraction over all the variations of suits.  Using <code>::card-suits</code> will be satisfied with any region specific suits.</p> <pre><code>(spec/def ::card-suits\n  (spec/or :french ::suits-french\n           :german ::suits-german\n           :spanish ::suits-spanish\n           :italian ::suits-italian\n           :swiss-german ::suits-swiss-german\n           :international ::suits-international))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#define-an-alias","title":"Define an alias","text":"<p>Jack queen king are called face cards in the USA and occasionally referred to as court cards in the UK.</p> <p>Define a spec for <code>::face-cards</code> and then define <code>:court-cards</code> and alias</p> <pre><code>(spec/def ::face-cards #{:jack :queen :king :ace})\n(spec/def ::court-cards ::face-cards)\n</code></pre> <p>Any value that conforms to the <code>::face-card</code> specification also conforms to the <code>::court-cards</code> specification.</p> <pre><code>(spec/conform ::court-cards :ace)\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#playing-card-rank","title":"Playing card rank","text":"<p>Each suit in the deck has the same rank of cards explicitly defining a rank</p> <pre><code>(spec/def ::rank #{:ace 2 3 4 5 6 7 8 9 10 :jack :queen :king})\n</code></pre> <p>Rank can be defined more succinctly with the <code>clojure.core/range</code> function.  The expression <code>(range 2 11)</code> will generates a sequence of integer numbers from 2 to 10 (the end number is exclusive, so 11 is not in the sequence).</p> <p>Using <code>clojure.core/into</code> this range of numbers can be added to the face card values.</p> <pre><code>(into #{:ace :jack :queen :king} (range 2 11))\n</code></pre> <p>The <code>::rank</code> specification now generates all the possible values for playing cards.</p> <pre><code>(spec/def ::rank (into #{:ace :jack :queen :king} (range 2 11)))\n</code></pre> <p>The specification only checks to see if a value is in the set, the order of the values in the set is irrelevant.</p>"},{"location":"clojure-spec/projects/card-game/#playing-card","title":"Playing Card","text":"<p>A playing card is a combination of suit and face value, a pair of values, referred to as a tuple.</p> <p>Clojure spec has a <code>tuple</code> function, however, we need to define some predicates first</p> <pre><code>(spec/def ::playing-card (spec/tuple ::rank ::suits ))\n</code></pre> <p>Use the spec with values to see if they conform.  Try you own values for a playing card.</p> <pre><code>(spec/conform ::playing-card [:ace :spades])\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#game-specs","title":"Game specs","text":"<p>Define specifications for data used to represent players and the overall card game.</p> <p>The player name is a very simple spec.</p> <pre><code>(spec/def ::name string?)\n</code></pre> <p>Score will keep a running total of a player score across games, again a simple integer value.</p> <pre><code>(spec/def ::score int?)\n</code></pre> <p>A player is represented by a hash-map that contains their name, score and the hand they are currently dealt.  The hand is a collection of tuples representing a playing card.</p> <pre><code>(spec/def ::player\n          (spec/keys\n            :req [::name ::score ::dealt-hand]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#game-deck-specs","title":"Game deck specs","text":"<p>A card game has a deck of 52 cards, one card for each combination of suit and rank.</p> <p>The size of the card deck changes over the course of a game, so the deck can contain any number of cards.  The deck must contain only cards to be valid.</p> <pre><code>(spec/def ::card-deck (spec/* ::playing-card))\n</code></pre> <p>At this stage in the design, a card game can have any number of players</p> <pre><code>(spec/def ::players (spec/* ::player))\n</code></pre> <p>A game is represented by a hash-map with a collection of players and a card deck</p> <pre><code>(spec/def ::game (spec/keys :req [::players ::card-deck]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#generative-data-from-specifications","title":"Generative data from Specifications","text":"<p>Clojure spec can generate random data which conforms to a specification, highly useful in testing Clojure code with a wide variety of values.</p> <ul> <li><code>clojure.spec.alpha/gen</code> returns a generator for the given specification.</li> <li><code>clojure.spec.gen.alpha/generate</code> takes that generator and creates a random value that conforms to the specification.</li> <li><code>clojure.spec.gen.alpha/sample</code> will generate a collection of random values that each conform to the specification.</li> </ul> <p>Require the clojure spec namespaces to make use of their functions.</p> <pre><code>(ns practicalli.card-game.clj\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]))\n\n(spec/def ::suits #{:clubs :diamonds :hearts :spades})\n(spec/def ::rank #{:ace 2 3 4 5 6 7 8 9 10 :jack :queen :king})\n</code></pre> <p>To generated data based on a specification, first get a generator for a given spec,</p> <pre><code>(spec/gen ::suits)\n</code></pre> <p><code>generate</code> will return a value using the specific generator for the specification.</p> <pre><code>(spec-gen/generate (spec/gen ::suits))\n</code></pre> <p><code>sample</code> will generate a number of values from the given specification</p> <pre><code>(spec-gen/sample (spec/gen ::rank))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#card-game-data","title":"Card Game data","text":"<p>Generate a random value for the <code>::player</code> specification</p> <pre><code>(spec-gen/generate (spec/gen ::player))\n</code></pre> Example <p>Expected output from <code>generate</code> ```clojure</p> <p>```</p> <p>Generate a random value for the <code>::game</code> specification</p> <pre><code>(spec-gen/generate (spec/gen ::game))\n</code></pre> <p>Generate a collection of random values that each conform to the specification.</p> <pre><code>(spec-gen/sample (spec/gen ::game))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#practicallispec-generative-testing","title":":practicalli.spec-generative-testing","text":"<p>{:name \"Yp34KE63vAL1eriKN4cBt\",  :score 225,  :dealt-hand ([9 :hearts] [4 :clubs] [8 :hearts] [10 :clubs] [:queen :spades] [3 :clubs] [6 :hearts] [8 :hearts] [7 :diamonds] [:king :spades] [:ace :diamonds] [2 :hearts] [4 :spades] [2 :clubs] [6 :clubs] [8 :diamonds] [6 :spades] [5 :spades] [:queen :clubs] [:queen :hearts] [6 :spades])}</p>"},{"location":"clojure-spec/projects/card-game/#function-specifications","title":"Function Specifications","text":"<p>A function specification can contain a specification for the arguments, the return values and the relationship between the two.</p> <p>The specifications for the function may be composed from previously defined data specifications.</p> <pre><code>(ns practicalli.card-game\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]))\n\n(spec/def ::suit #{:clubs :diamonds :hearts :spades})\n(spec/def ::rank (into #{:jack :queen :king :ace} (range 2 11)))\n(spec/def ::playing-card (spec/tuple ::rank ::suit))\n(spec/def ::dealt-hand (spec/* ::playing-card))\n\n(spec/def ::name string?)\n(spec/def ::score int?)\n(spec/def ::player (spec/keys :req [::name ::score ::dealt-hand]))\n(spec/def ::card-deck (spec/* ::playing-card))\n(spec/def ::players (spec/* ::player))\n(spec/def ::game (spec/keys :req [::players ::card-deck]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#function-definition","title":"Function definition","text":"<p>The card game application has three functions to start with.</p> <pre><code>(defn regulation-card-deck\n  \"Generate a complete deck of playing cards\"\n  [{:keys [::deck ::players] :as game}]\n  (apply + (count deck)\n         (map #(-&gt; % ::delt-hand count) players)))\n</code></pre> <p>At the start of function design, the algorithm may still be undefined.  Using the specifications and generators mock data can be returned as a placeholder.</p> <pre><code>(defn deal-cards\n  \"Deal cards to each of the players\n   Returns updated game hash-map\"\n  [game]\n  (spec-gen/generate (spec/gen ::game)))\n</code></pre> <pre><code>(defn winning-player\n  \"Calculate winning hand by comparing each players hand\n  Return winning player\"\n  [players]\n  (spec-gen/generate (spec/gen ::player)))\n</code></pre> Example <p>The expected form of a player won game:</p> <pre><code>  #:practicalli.player-won\n  {:name      \"Jenny Nada\",\n   :score     225,\n   :dealt-hand [[9 :hearts] [4 :clubs] [8 :hearts] [10 :clubs] [:queen :spades]]}\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#spec-definitions","title":"Spec definitions","text":"<p>Define a function specification for the <code>deal-cards</code> function</p> <ul> <li>argument must be of type <code>::game</code></li> <li>return type is <code>::game</code></li> <li>function applies arguments to a game and returns the game</li> </ul> <pre><code>(spec/fdef deal-cards\n  :args (spec/cat :game ::game)\n  :ret ::game\n  :fn #(= (regulation-card-deck (-&gt; % :args :game))\n          (regulation-card-deck (-&gt; % :ret))))\n</code></pre> <p>Define a function specification for the <code>winning-player</code> function</p> <ul> <li>argument must be of type <code>::players</code></li> <li>return type is <code>::players</code></li> </ul> <pre><code>(spec/fdef winning-player\n  :args (spec/cat :players ::players)\n  :ret ::player)\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#instrument-functions","title":"Instrument functions","text":"<p>Instrumenting functions will wrap a function definition and check the arguments of any call to the instrumented function.</p> <pre><code>(spec-test/instrument `deal-cards)\n</code></pre> <p>Calling the <code>deal-cards</code> function with an incorrect argument returns an error that describes where in the specification the error occurred.</p> <pre><code>(deal-cards \"fake game data\")\n</code></pre> <p>Error in an easier to read format</p> <pre><code>ERROR: #error\n {:message \"Call to #'practicalli.card-game/deal-cards did not conform to spec:\\n\\\n \"fake game data\\\" - failed:\n map? in: [0] at: [:args :game] spec: :practicalli.card-game/game\\n\",\n :data {:cljs.spec.alpha/problems\n [{:path [:args :game],\n   :pred cljs.core/map?,\n   :val \"fake game data\",\n   :via [:practicalli.card-game/game :practicalli.card-game/game],\n   :in [0]}],\n :cljs.spec.alpha/spec #object[cljs.spec.alpha.t_cljs$spec$alpha17968],\n :cljs.spec.alpha/value (\"fake game data\"),\n :cljs.spec.alpha/args (\"fake game data\"),\n :cljs.spec.alpha/failure :instrument}}\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#organizing-function-instrumentation","title":"Organizing function instrumentation","text":"<p>Instrumenting functions creates a wrapper around the original function definition.</p> <p>When you change the function definition and evaluate the new code, it replaces the instrumentation of the function.  Therefore each time a function is redefined it should be instrumented.</p> <p>There is no specific way to manage instrumenting a function, however, a common approach is to define a collection of functions to instrument, then use a helper function to instrument all the functions at once.</p> <p>Bind a name to the collection of function specifications.</p> <pre><code>(def ^:private function-specifications\n  [`card-game/deal-cards\n   `card-game/winning-player])\n</code></pre> <p>Define a simple helper function to instrument all the functions in the collection.</p> <pre><code>(defn instrument-all-functions\n  []\n  (spec-test/instrument function-specifications))\n</code></pre> <p>Refactoring the code may involve a number of changes benefit from instrumentation being switched off until its complete.  The <code>unstrument</code> function will remove instrumentation from all the functions in the collection.</p> <pre><code>(defn unstrument-all-functions\n  []\n  (spec-test/unstrument function-specifications))\n</code></pre> <p>Koacha Test Runner can include functional specifications</p> <p>Koacha test runner can manage the testing of function specifications and is especially useful for managing unit level testing with specifications.</p>"},{"location":"clojure-spec/testing/","title":"Testing with Specifications","text":""},{"location":"clojure-spec/testing/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"clojure-spec/testing/#during-development","title":"During development","text":"<p>Create specifications for data and functions</p> <p>Selectively instrument function definitions to check function call arguments against the function specification.</p> <ul> <li>clojure.spec.test.alpha/instrument - check fdef :args</li> </ul>"},{"location":"clojure-spec/testing/#unit-and-integration-testing","title":"Unit and integration testing","text":"<p>Add specification checks along with unit testing and integration testing to provide a very wide range of data values to be tested (with a minimal amount of code).</p> <ul> <li>clojure.spec.test.alpha/check - use :args to generate tests to check fdef :ret and :fn</li> </ul> <p>run a suite of spec-generative tests on an entire ns with <code>check</code>.  Just one namespace per <code>check</code> expression?</p> <p>control the number of values check creates for each check expression.  As the default is 1000 the checks can take a noticeable time to run (see practicalli/spec-generative-testing)</p> <p>Many built-in generators for <code>clojure.core</code> data predicates</p> <p>composite specifications can build generators upon predicate generators.</p> <p>Pass generator-returning functions to spec, supplying generators for things spec does not know about. Pass an override map to <code>gen</code> in order to supply alternative generators for one or more sub-paths of a spec.</p> <p>Define your own generators</p>"},{"location":"clojure-spec/testing/#at-run-time","title":"At run time","text":"<p>Use specifications for run time checking, typically using <code>conform</code> and <code>valid?</code> functions.</p> <p>Specification are typically the minimal checks required for the system, compared to more extensive checks during test and system integration.</p> <p>Create lightweight private specifications for tests that run in the production environment.</p>"},{"location":"clojure-spec/testing/checking%20arguments/","title":"Checking arguments in function calls with specifications","text":""},{"location":"clojure-spec/testing/checking%20arguments/#instrument-functions-during-development","title":"Instrument functions during development","text":"<p>Instrumenting a function enables the checking of arguments in a function call against the specification defined in an <code>fdef</code> definition of the same name.</p> <pre><code>(clojure.spec.test.alpha/instrument `function-name)\n</code></pre> <p>Instrumenting a function swaps the function definition var with a wrapped version of the function definition which includes tests the <code>:args</code> spec from the <code>fdef</code> expression.</p> <p><code>unstrument</code> returns the function definition to the original form and tests for that function are no longer run.</p>"},{"location":"clojure-spec/testing/checking%20arguments/#unit-specification-testing","title":"Unit (Specification) testing","text":"<p>You can generate data for interactive testing with gen/sample.</p>"},{"location":"coding-challenges/","title":"Coding Challenges for Clojure","text":"<p>Coding challenges are an excellent way to start learning a new language.  The challenges allow you to focus on the language and not be concerned about the more general engineering aspects of software development.</p> <p>Challenges are there to explore a language and practice your understanding of how to assemble working code.  It is recommended to try different approaches to solving a challenges and even repeat the same challenges at a later date and see what additional approaches you have learned.</p> <p>Exercism.io and 4Ever-Clojure are highly recommended starting point for learning Clojure and does not require any installation or setup.  4Ever-Clojure is a new implementation of 4Clojure.com.</p>"},{"location":"coding-challenges/#practicalli-challenges","title":"Practicalli Challenges","text":"<p>Challenge that can be solved in a few hours (or less).  Use a Clojure REPL connected editor to help solve these challenges. </p> <ul> <li>Simple Projects</li> <li>TDD Code Kata</li> </ul>"},{"location":"coding-challenges/#approach-to-solving-challenges","title":"Approach to solving challenges","text":"<p>Take a few minutes to digest the description of the challenge and make notes.</p> <p>Identify the simplest possible thing to do, solving the problem in many small pieces which encourages experimentation</p> <ul> <li>experiment, write code and evaluate to see what it does (optionally create a comment with the result)</li> <li>use a rich comment <code>(comment ,,,)</code> to capture multiple ideas and designs, even failed experiments can be useful (separates experiments from working code)</li> <li>continually evaluate code as expressions are written, to ensure their behaviour is understood (try different argument values for functions)</li> <li>try different shapes of data</li> <li>transform data shapes to keep function definitions simpler</li> </ul> <p>Once there is a working solution, refactor or try different approaches and evaluate the merit of alternative solutions</p>"},{"location":"coding-challenges/#challenge-websites","title":"Challenge websites","text":"<p>A local Clojure development environment supports solving challenge websites, e.g Clojure CLI and a Clojure REPl connected editor </p> Challenge website Description Requirements 4Ever-Clojure Learning the core functions of the Clojure language Web Browser Exercism Coding exercises with mentor support Web Browser &amp; Exercim CLI ClojureScript Koans Interactive exercises in a web browser Web Browser Advent of Code Yearly coding challenge with a seasonal theme Clojure aware editor CodeWars Mostly math-based coding challenges with Clojure variants Web Browser"},{"location":"coding-challenges/advent-of-code/","title":"Advent Of Code","text":""},{"location":"coding-challenges/advent-of-code/#advent-of-code","title":"Advent Of Code","text":"<p>Advent of Code is the annual coding challenge with a festive theme.  Each day there is a new challenge in two parts, the first fairly easy the second a little more involved.  The challenges are an investment of your time to complete them all, although even trying just a few is enough to help you think in different ways.</p> <p>Every programming language requires regular practice to maintain your skills.  A full time developer role gives lots of opportunities to practice every day, however, its often focused in around solving problems within a specific business domain, with little time to explore others.  The Advent of Code puts you in a different domain, so its great for extending your coding experiences.</p> <p>Solving challenges in a different language is another great way to extend your experiences, so here are some tips and examples for solving the advent of code in Clojure.</p>"},{"location":"coding-challenges/advent-of-code/#solving-challenges","title":"Solving challenges","text":"<ul> <li>Keep the solution as simple as possible.  Its very easy to over-complicate the solution and end up simply confusing yourself.</li> <li>Don't try and make the perfect solution.  Write something that works, this will give you a nice ego boost.  Then you can experiment with the code and see if you can improve your approach.</li> <li>Break down the problem into the simplest thing you can solve first.  Trying to solve a problem all at once will quickly have you going around in circles.</li> <li>Keep all the code and make notes.  I use a a design journal in my projects to document my thinking process, capture decisions that worked and those that didn't work for this project.  The journal is a great way to cement learning from solving the challenge.</li> <li>Challenges are only accessible from their day of the month onwards.  There is a count-down clock displayed on the next challenge to open, so you know when it will be available.  Don't feel pressured to keep up with the challenges though, enjoy the experience and have fun, you will learn more that way.</li> </ul>"},{"location":"coding-challenges/advent-of-code/#coding-video","title":"Coding video","text":"<p>A video guide to solving the first challenge of Advent of Code from 2018, trying out different solutions at increasing levels of abstraction.  With each level of abstraction it helps to think in a more functional way.</p> <p> </p>"},{"location":"coding-challenges/advent-of-code/#creating-a-project-for-the-challenge","title":"Creating a project for the challenge","text":"<pre><code>clojure -T:project/create :template lib practicalli.advent-of-clojure-code/2019\n</code></pre> <p>Create a new Clojure file for each of the daily challenges.  It makes sense to keep both parts of each day in the same file.</p> <p>Practicalli Advent Of Code solutions repository</p> <p>practicalli/advent-of-clojure-code-2019</p>"},{"location":"coding-challenges/advent-of-code/#useful-resources-and-examples","title":"Useful Resources And Examples","text":"<p>Videos and code solutions to many challenges from 2019 and past years.</p> <ul> <li>fdlk/advent-2019 - example Clojure solutions to the advent of code</li> <li>Awesome Advent Of Code - a collection of solutions in various languages</li> <li>Advent of Code 2018 video walk-through of Clojure solutions by Tim Pote and GitHub repository</li> </ul> <p>#adventofcode channel in the Clojurians slack channel discusses challenges and solutions, especially during December when the challenge takes place.</p>"},{"location":"coding-challenges/koans/","title":"ClojureScript Koans","text":"<p>Koans are a collection of small challenges that slowly increase in complexity.  They are similar to the 4Clojure challenges in scope.</p>"},{"location":"coding-challenges/koans/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"coding-challenges/4clojure/","title":"Coding Challenges: 4Clojure","text":"<p>4Ever-Clojure Challenges Website</p> <p>4Ever-Clojure is a simple website with 150 challenges to help discover the functions built-in to the Clojure language, the Clojure API.</p> <p>The website is self-contained with nothing to install, simply paste in the missing code and run the tests.  One piece of code should solve all the tests for that challenge.</p> <p>The Problem List shows the challenges categorized by experience level required, (Elementary, Easy, Medium, Hard) to solve them.  Start with the easiest problem or work your way through the challenges in any order you wish.  The Status column tracks your progress thorugh the challenges.</p> <p>Select the name of a challenge to see the description and one or more code tests that must pass.</p> <p>Enter the code that should be inserted where the <code>__</code> double underscore characters are.</p> <p>Press the Run button to see if the code satisfies the tests</p> <p>A dialog box is displayed showing how many tests have passed and failed</p> <p>Start learning the Clojure API</p> <p>There are over 600 functions in the <code>clojure.core</code> namespace alone, with additional functions in many other namespaces that make up the https://clojure.github.io/clojure/.  It is not required to learn all these functions to be productive in Clojure.</p> 4ever-clojure replaces 4Clojure <p>4Ever-Clojure is a new implementation of 4Clojure.com which has now been decommissioned</p>"},{"location":"coding-challenges/4clojure/#help-completing-the-challenges","title":"Help completing the challenges","text":"<p>Look at the Clojure Cheatsheet and Clojure API for an understanding of what functions are available in the core of the Clojure language.</p> <p>Search directly in ClojureDocs for functions.  Each function has a page that describes the function, shows the arguments it takes and provides many examples of its use.  At the end of the page are related functions too.</p> <p>Practicalli Code walk-through and solution journal</p> <p>practicalli/four-clojure code journals for the first 60 challenges contains a design journal showing how each challenge was solved and additional refactor or alternative approaches to the solution.</p> <p>Practicalli 4Clojure guides playlist provides video walk-through of the first 64 challenges, again with alternative solutions where relevant.</p> <p>An Internet search of <code>clojure topic</code>, where <code>topic</code> is a name of the thing you want to do, should return many examples of functions that could be useful to solving the challenge.  Or</p> <p>Help from the community</p> <p>Clojure community - getting help covers several sources of help from the Clojure community.</p>"},{"location":"coding-challenges/4clojure/#using-let-and-anonymous-functions","title":"Using let and anonymous functions","text":"<p>The solution submitted should be a single form, which is inserted in the test code where the <code>__</code> underscore placeholder is.  It is therefore not possible to define data with <code>def</code> or a separate function with <code>defn</code> to support the submitted solution.</p> <p>Use the anonymous function, <code>(fn [])</code>, to define behaviour.</p> <pre><code>(fn [value1 value2]\n  (* value1 value2))\n</code></pre> <p>Use let to bind a name to a value, so that value can be re-used throughout the expression.  <code>let</code> is also useful for breaking the algorithm into smaller pieces, making it easier to solve the challenge.</p> <pre><code>(let [name value]\n  (* 2 value (/ value 4) (+ value 3)))\n</code></pre> <p>It is common to combine <code>fn</code> and <code>let</code> to solve the challenges as they grow in complexity</p> <pre><code>(fn fibonacci [length-of-series]\n  (let [fib [1 1]]\n    (if (&lt; (count fib) length-of-series)\n      \"iterate... to implement\"\n      fib)))\n</code></pre> <ul> <li>fn - ClojureDocs</li> <li>let - ClojureDocs</li> <li>Fibonacci sequence guide - practicalli</li> </ul>"},{"location":"coding-challenges/4clojure/#my-function-is-not-working","title":"My function is not working","text":"<p>4Ever Clojure uses babashka/sci project to evaluate code on a JavaScript host.  Whist this should cover 99.9% of the Clojure API there may be some code that works in a Clojure (JVM) REPL that is not supported.</p> <p>Try the code in a Clojure REPL or create a Clojure project using the latest version of Clojure (1.11.x).</p>"},{"location":"coding-challenges/4clojure/#references","title":"References","text":"<ul> <li>4Ever-Clojure</li> <li>Clojure Cheatsheet - Clojure.org</li> <li>Clojure API - Clojure.org</li> <li>practicalli/four-clojure code journals for the first 60 challenges</li> <li>4Clojure video guides by Practicalli</li> <li>Clojure Core Library - ClojureDocs</li> <li>Clojure, The Essential Reference - Renzo Bogatti - Manning book published in 2020</li> </ul>"},{"location":"coding-challenges/codewars/","title":"CodeWars","text":"<p>Coding challenges in various languages with ranking scoreboard, experience levels and voting on solutions.  Many of the challenges tend toward mathematics, so may require some background research before solving them.</p>"},{"location":"coding-challenges/codewars/#requirements","title":"Requirements","text":"<p>Codewars is a web browser based system in which you can write code and run tests.  Sample unit tests are provided with each challenge, so its all self-contained.</p> <p>Create a free account and select the language you wish to attempt challenges in.  Two simple coding tests will need to be completed in order to access that specific language.</p>"},{"location":"coding-challenges/codewars/#challenges-dashboard","title":"Challenges Dashboard","text":"<p>After logging in, the dashboard suggests a challenge for you at a suitable level.  8 kyu is the easiest level, the smaller the number the harder the challenge.</p> <p></p>"},{"location":"coding-challenges/codewars/#tackling-a-challenge","title":"Tackling a challenge","text":"<p>Read the instructions and take a look at the sample tests.</p> <p>Many of the challenges have only a very basic explanation, so always review the sample unit tests to help with the understanding.  The sample tests are not necessarily the full suite of tests run when testing your solution, so there may be undocumented edge cases to solve</p> <p>The source and test code can be copied into a new project, as has been done with the practicalli/codewars-guides solutions</p> <pre><code>clojure -M:new lib practicalli/readability-is-king\n</code></pre> <p>Update the solution window with your solution and use the TEST button to run the sample unit tests.</p> <p>The ATTEMPT button will run all the unit tests for the challenge, which may be more than the sample tests.  If the attempt passes all the tests then the solution can be submitted an other solutions reviewed.</p> <p></p>"},{"location":"coding-challenges/codewars/#tracking-progress","title":"Tracking progress","text":"<p>View your profile page to track your progress and revisit kata challenges already completed.</p> <p></p>"},{"location":"coding-challenges/codewars/#references","title":"References","text":"<p>practicalli/codewars-guide - a repository of code solutions to CodeWars challenges, each challenge is its own Clojure CLI (deps.edn) project.</p> <p> YouTube: CodeWars video guides Unofficial Free Code Camp Clojure Challenges</p>"},{"location":"coding-challenges/exercism/","title":"Exercism Challenges","text":"<p> Exercism Clojure Track</p> <p> Exercism is a learning platform for multiple programming languates (currently 67) which combines carefully crafted coding challenges and mentors who review and advise on solutions.</p> <p>Solve challenges via the built-in Exercism editor.</p> <p></p> <p>Or download each exercise locally using the  Exercism CLI, providing a  Clojure CLI configured project with a test runner.</p> <p>Use the  Exercism CLI to submit a solution for metor feedback.</p> Exercism embdedded Clojure editor <p>The Exercisim Clojure editor is powered by  babashka/sci</p>"},{"location":"coding-challenges/exercism/#clojure-track","title":"Clojure Track","text":"<p>All the challenges are groups into specific  language tracks, including the  Clojure track</p> <p>Join the language track to be presented with available challenges and progress through that specific track.</p> <p></p>"},{"location":"coding-challenges/exercism/#working-locally","title":"Working Locally","text":"<p> Exercism Guide to working locally</p> <p>Follow the  Practicalli Clojure CLI Install steps (Exercism includes a similar  Clojure CLI install guide)</p> <p>The  Exercism CLI can download a Clojure project containing the code for a specific challeng and submit the code back to exercism to confirm if the tests have passed and complete the challenge (or get feedback from a mentor).</p> Each challenge shows the download and submit commands <p>Each Exercise page shows the command to download the code for that specific exercise, which is of the form <pre><code>exercism download --exercise=exercise-name --track=clojure\n</code></pre></p> <p>Open the project source code downloaded from Exercism in a  preferred Clojure editor and write a solution to solve the exercise.</p> <p><code>clojure -X:test</code> command in the root of the downloaded project will run the tests supplied by the exercise</p> Practicalli Test Runner aliases <p><code>clojure -X:test/run</code> runs the Kaocha test runner from the  Practicalli Clojure CLI Config</p> <p><code>clojure -X:test/watch</code> will automatically re-run tests when file changes are detected.</p> <p> Clojure test runner covers test runner options in more detail.</p> <p>Once the tests pass and you are happy with the solution, submit it to the Exercism website</p> <pre><code>exercism submit /path/to/src-file\n</code></pre>"},{"location":"coding-challenges/exercism/#repl-workflow","title":"REPL Workflow","text":"<p>Use a REPL workflow to get instant feedback on code written to make the unit test assersions pass.</p> Terminal UIEditor connected REPL <p>Start a REPL via a Terminal UI in the root of the Exercism project</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Open the project in a  Clojure aware editor and connect to the REPL process.</p> <p>Open the project in a  Clojure aware editor and start a Clojure REPL, e.g. jack-in</p> <p>Use a rich <code>comment</code> to experiment with clojure expressions that help move towards a solution, typically solving one unit test at a time. This separates experimental code from finished designs.</p> <pre><code>(comment \n  ;; experiment with clojure code \n  ;; evaluate expressions in the Clojure editor\n  ;; and see the evalaution results inline\n)\n</code></pre> <p>Disable Linter rules</p> <p>Disable Linter rules within the <code>comment</code> expression that are not useful for REPL experiments.</p> <p>It is common to have several implmentations of a function with the same name, so <code>:redefined-var</code> is disabled.</p> <p>Functions defined in the REPL experments are not ment to be used publicly (until they are copied/moved out of the comment form), so <code>:clojure-lsp/unused-public-var</code> lint rule is disabled <pre><code>#_{:clj-kondo/ignore [:redefined-var :clojure-lsp/unused-public-var]}\n(comment\n  ,,,\n)\n</code></pre></p>"},{"location":"coding-challenges/exercism/#support","title":"Support","text":"<p>Mentors on the Exercism website will provide a review of your submissions and you can switch between mentor and practice modes as you prefer.</p> <p> practicalli/exercism-clojure-guides contains a design journal of solutions to several Clojure exercises.</p> <p>Ask for advice in the #exercism or #beginners channels of the Clojurians Slack community.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/","title":"Nucleotide Count","text":"<p> Clojure Track: Nucleotide Count</p> <p>Given a string representing a DNA sequence, count how many of each nucleotide is present.</p> <p>If the string contains characters other than A, C, G, or T then an error should be throw.</p> <p>Represent a DNA sequence as an ordered collection of nucleotides, e.g. a string of characters such as \"ATTACG\".</p> <pre><code>\"GATTACA\" -&gt; 'A': 3, 'C': 1, 'G': 1, 'T': 2\n\"INVALID\" -&gt; error\n</code></pre> <p>DNA Nucleotide names</p> <p><code>A</code> is Adenine, <code>C</code> is Cytosine, <code>G</code> is Guanine and <code>T</code> is Thymine</p> <p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#create-the-project","title":"Create the project","text":"<p>Download the Nucleotide Count exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=nucleotide-count --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#starting-point","title":"Starting point","text":"<p>Unit test code calls functions from the <code>src</code> tree which must exist with the correct argument signature for the unit test code to compile successfully.</p> <p>Reviewing each assertion in the unit test code identifies the function definitions required.</p> Exercism Unit Tests <pre><code>(ns nucleotide-count-test\n  (:require [clojure.test :refer [deftest is]]\n            nucleotide-count))\n\n(deftest empty-dna-strand-has-no-adenosine\n  (is (= 0 (nucleotide-count/count-of-nucleotide-in-strand \\A, \"\"))))\n\n(deftest empty-dna-strand-has-no-nucleotides\n  (is (= {\\A 0, \\T 0, \\C 0, \\G 0}\n         (nucleotide-count/nucleotide-counts \"\"))))\n\n(deftest repetitive-cytidine-gets-counted\n  (is (= 5 (nucleotide-count/count-of-nucleotide-in-strand \\C \"CCCCC\"))))\n\n(deftest repetitive-sequence-has-only-guanosine\n  (is (= {\\A 0, \\T 0, \\C 0, \\G 8}\n         (nucleotide-count/nucleotide-counts \"GGGGGGGG\"))))\n\n(deftest counts-only-thymidine\n  (is (= 1 (nucleotide-count/count-of-nucleotide-in-strand \\T \"GGGGGTAACCCGG\"))))\n\n(deftest validates-nucleotides\n  (is (thrown? Throwable (nucleotide-count/count-of-nucleotide-in-strand \\X \"GACT\"))))\n\n(deftest counts-all-nucleotides\n  (let [s \"AGCTTTTCATTCTGACTGCAACGGGCAATATGTCTCTGTGTGGATTAAAAAAAGAGTGTCTGATAGCAGC\"]\n    (is (= {\\A 20, \\T 21, \\G 17, \\C 12}\n           (nucleotide-count/nucleotide-counts s)))))\n</code></pre> <p>Function definitions required to compile unit test code</p> src/nucleotide_count.clj<pre><code>(ns nucleotide-count)\n\n(defn count-of-nucleotide-in-strand\n  \"Count how many of a given nucleotide is in a strand\"\n  [nucleotide strand])\n\n(defn nucleotide-counts\n  \"Count all nucleotide in a strand\"\n  [strand])\n</code></pre>"},{"location":"coding-challenges/exercism/nucleotide-count/#making-the-tests-pass","title":"Making the tests pass","text":"<p>Select one assertion from the unit tests and write code to make the test pass.</p> <p>Experiment with solutions in the <code>comment</code> form and add the chosen approach to the respective function definition.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#counting-nucleotides","title":"Counting nucleotides","text":"<p>Use test data from the unit test code, e.g. <code>\"GGGGGTAACCCGG\"</code></p> <p>How often does a nucleotide appear</p> <p>Example</p> <pre><code>  (map\n    #(if (= % \\A) 1 0)\n    \"GGGGGTAACCCGG\")\n</code></pre> <p>Add the result to get the total count</p> <p>Example</p> <pre><code>  (count\n   (map\n     #(if (= % \\A) 1 0)\n     \"GGGGGTAACCCGG\"))\n</code></pre> <p>Is there a more elegant way?</p> <p>When only the matching nucleotide is in the strand, then all the elements of the strand can be counted.</p> <p><code>filter</code> the DNA strand with a predicate function (returns true/false) that returns only the matching nucleotide.</p> <p>Example</p> <pre><code>  (filter #(= % \\A) valid-nucleotides))\n</code></pre> <p>;; Count the elements in the returned sequence for the total</p> <p>Example</p> <pre><code>  (count\n   (filter #(= % \\A) valid-nucleotides))\n</code></pre> <p>Add this code into the starting function</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#run-unit-tests","title":"Run unit tests","text":"<p>Run the unit tests to see if they pass.  x should pass, x should fail.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#nucleotide-occurances","title":"Nucleotide occurances","text":"<p>Count the occurances</p> <p>\"GGGGGTAACCCGG\"</p> <pre><code>   (count\n     (filter (fn [nucleotide] (= nucleotide \\A))\n             \"GGGGGTAACCCGG\"))\n</code></pre> <p>Define the data</p> <pre><code>  (def valid-nucleotides\n    \"Characters representing valid nucleotides\"\n    [\\A \\C \\G \\T])\n</code></pre> <p>Exception handling required</p> <pre><code>(throw (Throwable.)) if nucleotide is \\X\n</code></pre> <p>Or use a predicate with some (some element? in the sequence)</p> <pre><code>  (some #(= \\G %) valid-nucleotides)\n\n  (some #{\\G} valid-nucleotides)\n</code></pre> <pre><code>  (defn count-of-nucleotide-in-strand\n    [nucleotide strand]\n    (if (some #(= nucleotide %) valid-nucleotides)\n      (count\n       (filter #(= nucleotide %)\n               strand))\n      (throw (Throwable.))))\n\n  (count-of-nucleotide-in-strand \\T \"GGGGGTAACCCGG\")\n</code></pre> <p>Design the second function</p> <p>How often does a nucleotide appear</p> <pre><code>  (map\n    #(if (= % \\A) 1 0)\n    valid-nucleotides)\n</code></pre> <p>Add the result to get the total count</p> <p>Is there a more elegant way?</p> <pre><code>  (filter #(= % \\A) valid-nucleotides)\n</code></pre> <p>Count the elements in the returned sequence for the total</p> <p>Design the second function</p> <p>How often does a nucleotide appear</p> <p>NOTE: zero must be returned when there are no appearences</p> <p>Return value always in the form</p> <pre><code>  {\\A 20, \\T 21, \\G 17, \\C 12}\n</code></pre>"},{"location":"coding-challenges/exercism/nucleotide-count/#hammock-time","title":"Hammock time...","text":"<ul> <li>How often does something appear,</li> <li>how frequenct is it?</li> <li>Is there a clojure standard library for that (approx 700 functions), review https://clojure-docs.org/</li> </ul> <pre><code>  (frequencies \"GGGGGAACCCGG\")\n</code></pre> <p>If there are missing nucleotides then there is no answer</p> <p>What if there is a starting point</p> <pre><code>  {\\A 0 \\C 0 \\G 0 \\T 0}\n</code></pre> <p>;; Then merge the result of frequencies</p> <pre><code>  (merge {\\A 0 \\C 0 \\G 0 \\T 0}\n         (frequencies \"GGGGGAACCCGG\"))\n</code></pre> <p>Update the function definition and run tests</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#solutions","title":"Solutions","text":"<p>There are many ways to solve a challenge and there is value trying different approaches to help learn more about the Clojure language.</p> <p>The following solution includes <code>filter</code> and <code>frequencies</code> functions which are commonly used functions from the Clojure standard library.</p> <p>Example Solution</p> src/nucleotide_count.clj<pre><code>(ns nucleotide-count)\n\n(def valid-nucleotides\n    \"Characters representing valid nucleotides\"\n    [\\A \\C \\G \\T])\n\n(defn count-of-nucleotide-in-strand\n  [nucleotide strand]\n  (if (some #(= nucleotide %) valid-nucleotides)\n    (count\n     (filter #(= nucleotide %)\n             strand))\n    (throw (Throwable.))))\n\n(defn nucleotide-counts\n  \"Count all nucleotide in a strand\"\n  [strand]\n  (merge {\\A 0 \\C 0 \\G 0 \\T 0}\n         (frequencies \"GGGGGAACCCGG\")))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/","title":"Exercise: RNA Transcription","text":"<p> Clojure Track: Nucleotide Count</p> <p>Given a DNA strand, return its RNA complement (per RNA transcription).</p> <p>Both DNA and RNA strands are a sequence of nucleotides.</p> <p>The four nucleotides found in DNA are adenine (A), cytosine (C), guanine (G) and thymine (T).</p> <p>The four nucleotides found in RNA are adenine (A), cytosine (C), guanine (G) and uracil (U).</p> <p>Given a DNA strand, its transcribed RNA strand is formed by replacing each nucleotide with its complement:</p> <ul> <li>G -&gt; C</li> <li>C -&gt; G</li> <li>T -&gt; A</li> <li>A -&gt; U</li> </ul> <p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#create-the-project","title":"Create the project","text":"<p>Download the RNA transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=rna-transcription --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#designing-the-solution","title":"Designing the solution","text":"<p>To convert a collection of values, define a hash-map where the keys are the initial DNA values and the hash-map values are the transformed RNA values.  Using a hash-map in this way is often termed as a dictionary.</p> <p>A string is used as a collection of character values by many of the functions in <code>clojure.core</code>.  The dictionary uses characters for its keys and values.</p> <pre><code>{\\G \\C \\C \\G \\T \\A \\A \\U}\n</code></pre> <p>Use the <code>map</code> function to pass the dictionary over the dna string (collection of characters) to create the RNA transcription.</p> <p>Use an anonymous function to wrap the dictionary and pass each a character (nucleotide) from the DNA string in turn.</p> <pre><code>(defn to-rna\n  [dna]\n  (map (fn [nucleotide] (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide))\n       dna))\n</code></pre> <pre><code>(to-rna \"GCTA\")\n</code></pre> <p>The result is returned as a sequence of characters.</p> <p>Refactor the <code>to-rna</code> function and add <code>clojure.string/join</code> to return the RNA value as a string</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide] (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide))\n         dna)))\n</code></pre> <p>Now the function returns a string rather than a collection of characters.</p> <pre><code>(to-rna \"GCTA\")\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#throwing-an-assertion-error-for-incorrect-nucleotide","title":"Throwing an assertion error for incorrect nucleotide","text":"<p>In the Exercism test suite, one test checks for an AssertionError when an incorrect nucleotide is passed as part of the DNA string.</p> <pre><code>(deftest it-validates-dna-strands\n  (is (thrown? AssertionError (rna-transcription/to-rna \"XCGFGGTDTTAA\"))))\n</code></pre> <p>The <code>throw</code> function can be use to return any of the Java errors. An assertion error would be thrown using the following code</p> <pre><code>(throw (AssertionError. \"Unknown nucleotide\"))\n</code></pre> <p>Refactor the <code>to-rna</code> function to throw an assertion error if a nucleotide if found that is not part of the dictionary.</p> <p>An <code>if</code> function could be used with a conditional to check if each nucleotide is one of the keys in the dictionary and throw an AssertionError if not found.  This would mean consulting the dictionary twice, once for the conditional check and once for the conversion.</p> <p>Is there a way to consult the dictionary once for each nucleotide?</p> <p>The <code>get</code> function can return a specific not-found value when a key is not found in a map.</p> <p>What if the <code>throw</code> function is used as the not-found value in the <code>get</code> function?</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide ](get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide\n                               (throw (AssertionError. \"Unknown nucleotide\")) ))\n         dna)))\n</code></pre> <p>Unfortunately this approach will evaluate the throw expression regardless of if the nucleotide is found in the dictionary, so calling this version of the function always fails.</p> <p>The <code>or</code> function evaluate the first expression and if a true value is returned then any additional expressions are skipped over.</p> <p>If the first expression returns false or a falsey value, i.e. <code>nil</code>, then the next expression is evaluated.</p> <p>Proposed Solution</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide](or (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide)\n                             (throw (AssertionError. \"Unknown nucleotide\"))))\n         dna)))\n</code></pre> <p>Call the <code>to-rna</code> function with a DNA string from the unit test code</p> <pre><code>(to-rna \"GCTA\")\n</code></pre> <p>The function should return <code>\"CGAU\"</code></p> <p>Call the <code>to-rna</code> function with a DNA string that contains an invalid nucleotide.</p> <pre><code>(to-rna \"GCXA\")\n</code></pre> <p>An <code>AssertionError</code> is thrown as the <code>X</code> character does not exist in the dictionary hash-map, so the <code>get</code> expression returns <code>nil</code>.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#refactor","title":"Refactor","text":"<p>Now the function is solving unit tests, minor adjustments can be made to streamline the code.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#hash-map-as-function","title":"Hash map as function","text":"<p>A hash-map can be called as a function and takes a key as an argument.  This acts the same as the <code>get</code> function, returning the value  associated to a matching key, otherwise returning <code>nil</code> or the not-found value if specified.</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide] (or ({\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide)\n                              (throw (AssertionError. \"Unknown nucleotide\"))))\n         dna)))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#anonymous-function","title":"Anonymous function","text":"<p>The anonymous function, <code>fn</code>, has a terse form.</p> <p><code>#(* %1 %2)</code> is the same as <code>(fn [value1 value2] (+ value1 value2))</code></p> <p>This syntax sugar is often use with <code>map</code>, <code>reduce</code>, <code>apply</code> functions as the behaviour tends to be compact and of single use.</p> <p>If the function definition is more complex or used elsewhere in the namespace, then the <code>defn</code> function should be used to define shared behavior.</p> <p>Solution with anonymous function</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map #(or ({\\G \\C \\C \\G \\T \\A \\A \\U} %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#named-dictionary-data","title":"Named dictionary data","text":"<p>Replace the hard-coded hash-map by defining a name for the dictionary.</p> <p>Define a name to represent the dictionary data</p> <pre><code>(def dictionary-dna-rna {\\G \\C \\C \\G \\T \\A \\A \\U})\n</code></pre> <p>Refactor the <code>to-rna</code> function to use the dictionary by name.</p> <p>Solution using named dictionary data</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map #(or (dictionary-dna-rna %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna)))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#making-the-function-pure","title":"Making the function pure","text":"<p>Its beyond the scope of the Exercism challenge, however, its recommended to use pure functions where possible.</p> <p>A pure function only uses data from its arguments.</p> <p>Adding a dictionary as an argument to the <code>to-rna</code> function would be simple.</p> <p>Pure function approach</p> <pre><code>(defn to-rna\n  [dictionary dna]\n  (clojure.string/join\n    (map #(or (dictionary %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre> <p>With a dictionary as an argument the function is also more usable, as other dictionaries could be used with the function.</p> <p>The function would now be called as follows</p> <pre><code>(to-rna dictionary-dna-rna \"GTGAC\")\n</code></pre>"},{"location":"coding-challenges/exercism/space-age/","title":"Space Age","text":""},{"location":"coding-challenges/exercism/space-age/#topics-covered","title":"Topics covered","text":"<p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/space-age/#create-the-project","title":"Create the project","text":"<p>Download the RNA transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=rna-transcription --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/space-age/#challenge-introduction","title":"Challenge introduction","text":"<p>Given an age in seconds, calculate how old someone would be on:</p> <ul> <li>Earth: orbital period 365.25 Earth days, or 31557600 seconds</li> <li>Mercury: orbital period 0.2408467 Earth years</li> <li>Venus: orbital period 0.61519726 Earth years</li> <li>Mars: orbital period 1.8808158 Earth years</li> <li>Jupiter: orbital period 11.862615 Earth years</li> <li>Saturn: orbital period 29.447498 Earth years</li> <li>Uranus: orbital period 84.016846 Earth years</li> <li>Neptune: orbital period 164.79132 Earth years</li> </ul> <p>So if you were told someone were 1,000,000,000 seconds old, you should be able to say that they're 31.69 Earth-years old.</p>"},{"location":"coding-challenges/exercism/bob/","title":"Index","text":""},{"location":"coding-challenges/exercism/bob/#bob","title":"Bob","text":"<p>The Bob challenge involves writing a very basics example of a text parser, something that would be used for a text based adventure game.</p> <p>Bob is described as a lackadaisical teenager, so responses are very limited.  To create the Bob text parser we need to identify the rules that determine Bob's response.</p> <p>The instructions provide some basic rules:</p> <ul> <li>Bob answers 'Sure.' if you ask him a question.</li> <li>He answers 'Whoa, chill out!' if you yell at him.</li> <li>He answers 'Calm down, I know what I'm doing!' if you yell a question at him.</li> <li>He says 'Fine. Be that way!' if you address him without actually saying anything.</li> <li>He answers 'Whatever.' to anything else.</li> </ul> <p>It is important to also read through the supplied unit tests to elaborate on these rules.</p>"},{"location":"coding-challenges/exercism/bob/#create-the-project","title":"Create the project","text":"<p>Download the Bob transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=bob --track=clojure\n</code></pre> <p>To use the Clojure CLI tool instead of Leiningen, create a <code>deps.edn</code> file containing an empty hash-map, <code>{}</code> and clone  Practicalli Clojure CLI Config to <code>~/.clojure/</code>.</p>"},{"location":"coding-challenges/exercism/bob/#rules-derived-from-the-unit-tests","title":"Rules derived from the Unit tests","text":"<p>Reviewing all the examples from the unit tests, there are 5 rules for the Bob parser</p> <p>These rules were discovered by searching through the unit test code for each reply that Bob should return, showing the tests for each reply.</p> <p>Each rule also had to ensure it did not create any false positives by being true for any other reply that Bob could make, especially the whatever reply.</p> Name Rule description question The phrase has a ? as the last alphanumeric character, not including whitespace shouting The phrase has uppercase alphabetic characters, but no lower case alphabetic characters shouting question A combination of question and shouting silence The phrase is empty or contains characters that are not alphanumeric whatever Any phrase that does not match any of the other rules"},{"location":"coding-challenges/exercism/bob/#design-approach","title":"Design approach","text":"<p>There are two main approaches to solving this challenge.  The first is to use the <code>clojure.string</code> functions to check or transform the phrase given to Bob.  The second approach is to use regular expressions with functions such as <code>re-seq</code>, <code>re-find</code> and <code>re-matches</code>.</p> <p>Start by defining the rules as an expression that returns either true or false, using some of the example strings from the unit tests.</p> <p>Use a <code>let</code> expression to bind a name to each rule, e.g. <code>shouting?</code>, <code>question?</code>, <code>silence?</code>.  Then these names can be used in a simple <code>cond</code> expression to return the appropriate phrase.  Regardless of if using <code>clojure.string</code> or regular expressions, the <code>cond</code> code should be similar</p> <p>Once you have tried this challenge for yourself, take a look at the design journal for the clojure.string approach and the regular expression approach.</p> <p>Bob - clojure.string approach Bob - regular expression approach</p>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/","title":"Bob solution - regex","text":"<p>Solution to Bob challenge using regular expressions and the <code>re-matches</code> function.</p> <p>Using <code>re-matchers</code>, if the string matches the pattern, then the string is returned. Otherwise <code>nil</code> is returned</p> <p>The regular expressions cheatsheet from Mozilla Developer Network was very helpful in understanding regular expressions</p>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#asking-bob-a-question","title":"Asking Bob a question?","text":"<p>The phrase passed to Bob is a question if the last alphanumeric character is a question mark. Using a simple regular expression we can check if the last character in the string a <code>?</code></p> <p><code>#\"\\?\"</code> is a literal regular expression pattern that will match a single <code>?</code> character</p> <p>So the regular expression pattern will match a single ? character</p> <pre><code>  (re-matches #\"\\?\" \"?\")\n</code></pre> <p>With other characters present though the pattern doesn't match.</p> <pre><code>  (re-matches #\"\\?\" \"Ready?\")\n</code></pre> <p>To match <code>?</code> with other characters,</p> <p><code>.</code> matches any single character except line terminators (new line, carriage return)</p> <pre><code>(re-matches #\".\\?\" \"R?\")\n</code></pre> <p><code>.*</code> matches any number of single characters one or more times,</p> <pre><code>(re-matches #\".*\\?\" \"?Ready\")\n</code></pre> <p><code>\\s</code> matches a single whitespace character and <code>\\s*</code> matches multiple whitespace characters</p> <pre><code>  (re-matches #\".*\\?$\" \"Okay if like my  spacebar  quite a bit?\")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit?\"\n</code></pre> <p><code>$</code> is a boundary assertion so the pattern only matches the ? at the end of a string and not in the middle.  However, this is not required as the <code>re-matches</code> uses groups and that manages the boundary assertion.</p> <p><code>re-matches</code> does not require the <code>$</code> as there is an implicit boundary</p> <pre><code>  (re-matches #\".*\\?\" \"Okay if like my ? spacebar  quite a bit\")\n</code></pre> <p>Match if there is a single space or space type character after the ?</p> <pre><code>  (re-matches #\".*\\?\\s\" \"Okay if like my  spacebar  quite a bit? \")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit? \"\n</code></pre> <p>Match if there are multiple space type characters after the ?</p> <pre><code>  (re-matches #\".*\\?\\s*\" \"Okay if like my  spacebar  quite a bit?   \")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit?   \"\n</code></pre> <p>Don't match if a question mark character is not at the end of the string</p> <pre><code>  (re-matches #\".*\\?\" \"Okay if like my ? spacebar  quite a bit\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#shouting-a-question-at-bob","title":"Shouting a question at Bob","text":"<p><code>[^a-z]</code> matches if there are no lower case alphabetic characters.  The <code>^</code> at the start of the pattern negated the pattern.</p> <p><code>*</code> any number of the proceeding pattern</p> <p><code>[A-Z]+</code> any number of upper case alphabetic characters</p> <p>When a phrase has all uppercase characters then we have a match</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"HELLO\")\n</code></pre> <p>If there are lower case characters, even if there are uppercase characters, the pattern does not match.</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"Hello\")\n</code></pre> <p>If the characters are all uppercase then the pattern matches, even if there are other non-alphabetic characters</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"ABC 1 2 3\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#silence-of-the-bob","title":"Silence of the Bob","text":"<p><code>\\s</code> matches any single whitespace character, including space, tab, form feed, line feed, and other Unicode spaces.</p> <pre><code>(re-matches #\"\\s*\" \"  \\t\\t\\t\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#solution-using-regular-expressions","title":"Solution using regular expressions","text":"<p>The <code>re-matches</code> expressions with regular expressions patterns can be put into a let expression.  The names are bound to the re-matches expressions which evaluated to either <code>true</code> or <code>false</code></p> <p>The names from the let are used with a <code>cond</code> function as conditions, returning the relevant reply from Bob.</p> <p>For the shouting question, the <code>and</code> is used to check if two names are both true.</p> <pre><code>(defn response-for\n  [phrase]\n  (let [;; A ? at the end of the phrase, not counting whitespace\n        question (re-matches #\".*\\?\\s*\" phrase)\n\n        ;; No lower case characters, at least one upper case character\n        yelling (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" phrase)\n\n        ;; The entire string is whitespace\n        silence (re-matches #\"\\s*\" phrase)]\n\n    (cond\n      silence                \"Fine. Be that way!\"\n      (and question yelling) \"Calm down, I know what I'm doing!\"\n      question               \"Sure.\"\n      yelling                \"Whoa, chill out!\"\n      :whatever              \"Whatever.\")))\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/","title":"Bob string approach","text":"<p>Solution to Bob challenge using <code>clojure.string</code> functions and Character class from Java.</p>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#asking-bob-a-question","title":"Asking Bob a question?","text":"<p>The phrase passed to Bob is a question if the last alphanumeric character is a question mark.</p> <p>Using a simple comparison we can check if the last character in the string a <code>?</code></p> <pre><code>(= \\? (last \"this is a question?\"))\n</code></pre> <p>However if there is whitespace after the question mark then the <code>last</code> character is a whitespace and so the expression returns false</p> <pre><code>  (= \\? (last \"this is still a question? \"))\n</code></pre> <p><code>clojure.string/trimr</code> will remove all the trailing whitespace from the right side of a string.  Once trimmed, then our initial comparison code will work again.</p> <pre><code>  (= \\? (last (clojure.string/trimr \"this is still a question? \")))\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#shouting-at-bob","title":"Shouting at Bob","text":"<p>Unfortunately the  clojure.string API does not have a function to check if a string is in capital letters.  There is an <code>upper-case</code> function, so a comparison can be made  with the original string and the string returned from <code>clojure.string/upper-case</code>.</p> <p>Convert the string to uppercase</p> <pre><code>(clojure.string/upper-case \"watch out!\")\n</code></pre> <p>compare the uppercase version of the string with the original, if they are equal, then the original string must have been in upper case</p> <pre><code>  (= \"WATCH OUT!\"\n     (clojure.string/upper-case \"WATCH OUT!\"))\n</code></pre> <pre><code>  (= \"watch out!\"\n     (clojure.string/upper-case \"watch out!\"))\n</code></pre> <p>There is a flaw in this approach thought, as it will give false positives for strings that should return the 'Whatever' response</p> <pre><code>  (= \"1, 2, 3\"\n     (clojure.string/upper-case \"1, 2, 3\"))\n</code></pre> <p>Refined rule to check that the phrase contains alphabetic characters, otherwise it is not shouting.</p> <p>The java.lang.Character class has a method called isLetter that determines if a character is a letter.</p> <p>The Classes and methods in <code>java.lang</code> are always available within a Clojure project, without the need for specifically importing the library.</p> <p><code>Character/isLetter</code> can be called as a function in Clojure, passing in a character type.</p> <pre><code>(Character/isLetter \\a)\n</code></pre> <p>To support all Unicode characters there is an isLetter method that takes an integer type.  As there could be any kind of characters in the phrase, we will use the int version.  This required conversing the character to an int first before calling <code>Character/isLetter</code></p> <pre><code>(Character/isLetter (int \\a))\n</code></pre> <p>the <code>some</code> function is used to iterate over all the characters in the phrase. As soon as a letter is found it returns true, so does not need to process the whole phrase unless no letter is found.</p> <pre><code>(some #(Character/isLetter (int %)) phrase)\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#silence-of-the-bob","title":"Silence of the Bob","text":"<p><code>clojure.string/blank?</code> is a predicate function that returns true if a string is empty or contains only whitespace.  It also returns true for a <code>nil</code> value.</p>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#final-solution","title":"Final solution","text":"<p>Each of the rules is bound to a name that represents either a true or false value returned from each expression.</p> <p>The <code>cond</code> expression then evaluates the local names to see if they are true or false.  The first true value found returns the string associated with the name.</p> <p>For the shouting question, the <code>and</code> is used to check if two names are both true.</p> <pre><code>(defn response-for [phrase]\n  (let [phrase    (string/trimr phrase)\n        silence?  (string/blank? phrase)\n        question? (= \\? (last phrase))\n        letters?  (some #(Character/isLetter (int %)) phrase)\n        shouting? (and (= phrase (string/upper-case phrase))\n                       letters?)]\n    (cond\n      (and shouting? question?) \"Calm down, I know what I'm doing!\"\n      silence?                  \"Fine. Be that way!\"\n      shouting?                 \"Whoa, chill out!\"\n      question?                 \"Sure.\"\n      :else                     \"Whatever.\")))\n</code></pre> <p>The first let binding, <code>phrase</code> over-rides the name of the argument to the function.  This is not that common an approach as over-riding can lead to confusion.  However, in this relatively simple example it feels okay to do.  The over-ride is the first let binding and it is preparing the string for all the other let bindings to use.</p> <p>Over-riding names of functions from the Clojure standard library is not recommended as this does lead to much confusion.</p>"},{"location":"coding-challenges/palindrome/","title":"Project Palindrome","text":"<p>In this section we will create a simple Clojure project using Leiningen and build up a palindrome checker step by step.</p> <p>We will start with the simplest possible thing we can create and steadily add</p>"},{"location":"coding-challenges/palindrome/#what-is-a-palindrome","title":"What is a Palindrome","text":"<p>For this project it is assumed that a palindrome is a string of characters from the English alphabet and not any other language or an alphanumeric sequence.</p> <p>It is assumed that a palindrome is at least 3 characters long, meaning a single character cannot be a palindrome.  If a single character was a palindrome, then any valid sequence would contain at least as many palindromes as characters in that sequence.</p>"},{"location":"coding-challenges/palindrome/#challenge","title":"Challenge","text":"<p>Write an algorithm to find the 3 longest unique palindromes in a string. For the 3 longest palindromes, report the palindrome, start index and length in descending order of length. Any tests should be included with the submission.</p> <p>For example, the output for string, <code>\"sqrrqabccbatudefggfedvwhijkllkjihxymnnmzpop\"</code> should be:</p> <pre><code>Text: hijkllkjih, Index: 23, Length: 10\nText: defggfed, Index: 13, Length: 8\nText: abccba, Index: 5 Length: 6\n</code></pre> <ul> <li>Check for a palindrome</li> <li>Generate a series of palindromes</li> </ul>"},{"location":"coding-challenges/palindrome/simple-palindrome-test/","title":"Simple palindrome test","text":""},{"location":"continuous-integration/","title":"Continuous Integration","text":"<p>Topics to be covered in this section include:</p> <ul> <li> Continuous Integration services</li> <li> Circle CI</li> <li> GitHub Workflow</li> <li> GitLab CI</li> <li> Configure deployment pipelines</li> <li> Manage environment variables</li> <li> Security &amp; Secrets</li> <li> Deployment</li> <li> Amazon AWS</li> <li> Render.com</li> </ul> <p>CircleCI example in Practicalli Clojure Web Services</p> <p>Banking on Clojure is an example of Continuous Integration using CircleCI, with LambdaIsland/Kaocha as the test runner and Heroku as the deployment pipeline.</p>"},{"location":"continuous-integration/#12-factor-approach","title":"12 Factor approach","text":"<p>Following the 12 factor principles, the deployment is driven by source code to multiple environments.</p>"},{"location":"continuous-integration/#circleci-service","title":"CircleCI service","text":"<p>Use Yaml language to write CI workflows and tasks, using Docker images as a consistent run-time environment</p> <p>A commercial service with a generous free Cloud plan - (6,000 minutes), providing highly optomises container images to run tasks efficiently.  The CircleCI Clojure images contain Clojure CLI, Leiningen and Babashka pre-installed.</p> <p>CircleCI Orbs package up common configuration and tools, greatly simplifying the configuration and maintenance required.</p> <p>CircleCI Clojure language guide</p>"},{"location":"continuous-integration/#github-workflow","title":"GitHub Workflow","text":"<p>Use Yaml language to write CI workflows and tasks.</p> <p>A commercial service with a modest free plan (2,000 minutes) for open source projects.  GitHub Marketplace contains a wide range of Actions, including Clojure related actions, simplifying the configuration of CI.</p> <p>Setup Clojure provides Clojure CLI, Leinigen and boot tools for use within the CI workflow</p> <p>GitHub Actions overview</p>"},{"location":"continuous-integration/circle-ci/","title":"Circle CI continuous integration service","text":"<p>Circle CI is a service to build, test and deploy projects.  CircleCI uses docker images to run its workflow, either in the cloud or locally.</p> <p>Projects can be build, tests run, artifacts (uberjars) created and applications deployed to services such as AWS, Render.com, etc.</p> <p>Integration will be supported by Git version control, a continuous integration service (CircleCI, GitLabs, GitHub Actions) and a deployment platform (Heroku).</p>"},{"location":"continuous-integration/circle-ci/#getting-started","title":"Getting Started","text":"<p>Sign up using a GitHub or Bitbucket account and login to the CircleCI dashboard.</p> <p>Add Project in the CircleCI dashboard to configure a shared Git repository and run build pipelines using a <code>.circleci/config.yml</code> file in the root of the Clojure project.</p> <p>Every time changes are pushed to the shared code repository (GitHub, Bitbucket), CirceCI will run the pipeline for the project and show the results.</p>"},{"location":"continuous-integration/circle-ci/#clojure-images","title":"Clojure images","text":"<p>Clojure specific container images are available for several versions of Java and Clojure.  Pre-configured images are typically faster than installing software on top a more generic image.</p> <p><code>cimg/clojure:1.10</code> is the recommended image for Clojure projects. The image contains OpenJDK 17 and the latest version of Clojure CLI, Leiningen and Babashka</p> <p>Add the following under the <code>docker:</code> key in the <code>config.yml</code></p> <pre><code>- image: cimg/clojure:1.10\n</code></pre> <p>The CircleCI Clojure Language guide walks through the sections of the yaml configuration in detail.</p> Check Clojure version <p><code>clojure -Sdescribe</code> shows configuration information for the Clojure CLI tool as a hash-map, with the :version key associated with the exact install version.</p> <p><code>lein version</code> shows the current version of Leiningen install on your development environment.</p> <p><code>java -version</code> shows the current version of the Java installation.</p>"},{"location":"continuous-integration/circle-ci/#references","title":"References","text":"<p>CircleCI Clojure Language guide CircleCI Clojure image tags - json   CircleCI Clojure images  CircleCI dockerfiles repository</p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/","title":"Circle CI example project","text":"<p>The Circle CI language guide for Clojure provides an example project that is managed by the Leiningen build automation tool and based on the Luminus micro-framework template.</p> <p>The project runs on the Undertow web server (wrapped by immutant), using ring to manage web requests and responses, with compojure for server-side routing.  The application uses mount to manage the application lifecycle.</p> <p>Fork the CircleCI-Public/circleci-demo-clojure-luminus project on your GitHub or GitLab account or organisation.</p> <p>Go to the CircleCI dashboard and login.  Select the GitHub / GitLab organisation you want to work with, this will list the repositories in that organisation.</p> <p></p> <p>Find the project in the list of repositories for that organisation</p> <p></p> <p>Click on the \"Set Up Project\" button and select the Clojure configuration from the drop-down menu.</p> <p></p> <p>This template seems to be older than the sample configuration on the Clojure language page.  Copy the sample configuration and paste it into the editor.  Then press Add Config to automatically add it to your code repository.</p> <p>This will start a build and show the pipelines dashboard, with the project running the tasks defined in the configuration</p> <p></p> <p>Oh, it failed...</p> <p></p> <p>Clicking on the FAILED button shows details of that particular pipeline.  This opens the build report for the pipeline.</p> <p>The build report shows all the steps that have passed and the details of the step which has failed, in this case lein do test, uberjar</p> <p></p> <p>Edit the <code>.circleci/config.yml</code> file in your fork and change the images used to <code>openjdk-8-lein-2.9.3</code>.</p> <p>Then commit the change to the code in the code repository. Another build will run automatically.</p> <p></p> <p>The dashboard shows the second build of this pipeline, showing the new commit just pushed</p> <p></p> <p>Success.  Now development can continue knowing the configuration of the pipeline works.</p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/#hintfailing-on-java-11","title":"Hint::Failing on Java 11","text":"<p>The example project only seems to run on Java 8.  Running the project locally with either <code>lein run</code> or <code>lein test</code></p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/#hintcannot-edit-configuration-via-dashboard","title":"Hint::Cannot edit configuration via dashboard","text":"<p>Apart from the initial creation of the configuration, its not possible to edit the configuration via the dashboard.</p>"},{"location":"continuous-integration/circle-ci/detailed-config/","title":"Circle CI detailed configuration","text":""},{"location":"continuous-integration/circle-ci/detailed-config/#orbs","title":"Orbs","text":"<p>CircleCI Orbs are pre-packaged configurations for specific tasks, reducing the amount of configuration to maintain.</p> Orbs Description h-matsuo/github-release@0.1.3 GitHub release - package up releases ? Deploy to Heroku Kaocha test runner - unit and generative testing, junit-xml reports and test coverage"},{"location":"continuous-integration/circle-ci/detailed-config/#executors","title":"Executors","text":"<p>Define an executor for the environment used to run the CircleCI jobs.</p> Executor environment Description machine Linux virtual machine docker <p>Configuration for a Clojure CLI project</p> <pre><code>---\nversion: 2.1\n\norbs:\n  github-release: h-matsuo/github-release@0.1.3\n\nexecutors:\n  tools-deps-executor:\n    docker:\n      - image: circleci/clojure:openjdk-11-tools-deps-1.10.1.697\n    working_directory: ~/repo\n    environment:\n      JVM_OPTS: -Xmx3200m\n\ncommands:\n  setup:\n    steps:\n      - checkout\n      - restore_cache:\n          keys:\n            - v1-dependencies-{{ checksum \"deps.edn\" }}\n            - v1-dependencies-\n      - save_cache:\n          paths:\n            - ~/.m2\n          key: v1-dependencies-{{ checksum \"deps.edn\" }}\n\n  acceptance-tests:\n    steps:\n      - run:\n          name: check coverage\n          command: clojure -M:test:coverage\n\n  deploy-version:\n    steps:\n      - run:\n          name: Update pom.xml\n          command: clojure -Spom\n      - run:\n          name: Build\n          command: clojure -M:jar\n      - run:\n          name: Deploy\n          command: clojure -M:deploy\n\n  store-artifact:\n    steps:\n      - run:\n          name: Create jar\n          command: clojure -M:jar\n      - run:\n          name: Zip up jar file\n          command: zip --junk-paths github-api-lib github-api-lib.jar\n      - run:\n          name: install mvn\n          command: |\n            sudo apt-get update\n            sudo apt-get -y install maven\n      - run:\n          name: extract version from pom\n          command: |\n            mvn help:evaluate -Dexpression=project.version -q -DforceStdout &gt; current_version\n      - persist_to_workspace:\n          root: ~/repo\n          paths:\n            - github-api-lib.zip\n            - current_version\n\n  create-release:\n    steps:\n      - attach_workspace:\n          at: ~/repo\n      - github-release/create:\n          tag: \"v$(cat ~/repo/current_version)\"\n          title: \"Version v$(cat ~/repo/current_version)\"\n          description: \"Github-related API calls.\"\n          file-path: ~/repo/github-api-lib.zip\n\n\n\njobs:\n  test:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - acceptance-tests\n  deploy:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - acceptance-tests\n      - deploy-version\n  artifact:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - store-artifact\n  release:\n    executor: github-release/default\n    steps:\n      - setup\n      - create-release\n\n\nworkflows:\n  build-test-release:\n    jobs:\n      - test\n      - deploy:\n          context: clojars\n          requires:\n            - test\n          filters:\n            branches:\n              only: main\n      - artifact:\n          requires:\n            - test\n          filters:\n            branches:\n              only: main\n      - release:\n          context: github\n          requires:\n            - test\n            - deploy\n            - artifact\n          filters:\n            branches:\n              only: main\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/","title":"Random Clojure Function","text":"<p>A Clojure command line application that shows a random function from the namespaces available in the Clojure Standard library, or a specific namespace from that library.</p> <p>Random Clojure Function repository</p> <p>This guide shows how to develop this project alongside CircleCI as the continuous integration service.</p> <ol> <li>Create a new project - using the Random Clojure Function guide</li> <li>Create a repository on GitHub</li> <li>Commit the project early and push changes to GitHub</li> <li>Add a .circleci/config.yml file and push to GitHub, choosing the relevant image</li> <li>Login to CircleCI dashboard and add project, choosing manual configuration</li> <li>Continue developing the random clojure function project, including tests</li> <li>After each push to GitHub, check the build status</li> <li>Add a CircleCI badge to the project readme</li> </ol> <p> </p> <p>Video uses an older command to create projects</p> <p><code>:project/create</code> alias from  Practicalli Clojure CLI Config creates a new project</p> <p>Arguments are key value pairs and can specify the <code>:template</code>, project <code>:name</code> and outpug directory <code>:output-dir</code>. <pre><code>clojure -T:project/new :template app :name practicalli/playground`\n</code></pre></p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#create-a-new-project","title":"Create a new project","text":"<p>Start following the guide to create the random clojure function project, using a deps.edn for the Clojure project configuration</p> <pre><code>clojure -T:project/new :template app :name practicalli/random-clojure-function\n</code></pre> <p>Version control the Clojure project using Git (or magit in Spacemacs)</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#add-a-test-run-alias","title":"Add a test run alias","text":"<p>Edit the <code>deps.edn</code> file in the root of the project and add a <code>:test/run</code> alias, to run the kaocha test runner which will stop if a failing test is detected.  Stopping on a failed test saves running the full test suite and make the CI workflow more effective.</p> Project deps.edn<pre><code>:test/run\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.60.977\"}}\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:randomize? false\n             :fail-fast? true}}\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#create-a-remote-repository","title":"Create a remote repository","text":"<p>Add the remote repository URL to the local Git repository.</p> <pre><code>git remote add practicalli git@github.com:practicalli/random-clojure-function.git\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#add-circleci-configuration","title":"Add CircleCI configuration","text":"<p>Adding CircleCI early in the project development cycle ensures testing from the saved source code is successful and testing is consistently repeatable.</p> <p>Create a new file called <code>.circleci/config.yaml</code> in the root of the project.</p> <p>Edit the file and add the following configuration.</p> <p>Circe CI configuration for Clojure project</p> <p><code>``yaml title=\".circleci/config.yaml\" version: 2.1 jobs:                                               # basic units of work in a run   build:                                            # runs without Workflows must have a</code>build<code>job as entry point     working_directory: ~/random-clojure-function    # directory where steps will run     docker:                                         # run the steps with Docker       - image:  cimg/clojure:1.10                   # image is primary container where</code>steps<code>are run     environment:                                    # environment variables for primary container       JVM_OPTS: -Xmx3200m                           # limit maximum JVM heap size to prevent out of memory errors     steps:                                          # commands that comprise the</code>build` job       - checkout                                    # check out source code to working directory       - restore_cache:                              # restores cache if checksum unchanged from last run           key: random-clojure-function-{{ checksum \"deps.edn\" }}       - run: clojure -P       - save_cache:                                 # generate / update cache in the .m2 directory using a key template           paths:             - ~/.m2             - ~/.gitlibs           key: random-clojure-function-{{ checksum \"deps.edn\" }}       - run: clojure -X:test/run</p> <p>```</p> <p><code>run: clojure -P</code> step downloads dependencies for the project, including the <code>:extra-deps</code> if aliases are also included.</p> <p><code>run: clojure -X:test/run</code> adds the test directory to the class path and runs the Kaocha runner defined in the alias.</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#connect-circle-ci-to-the-project","title":"Connect Circle CI to the project","text":"<p>Commit and push the <code>.circleci/config.yml</code> file to the GitHub repository.</p> <p>Open the CircleCI dashboard and select Add Project.  If your GitHub account has multiple organizations, choose the appropriate organization first.</p> <p>Search the repository list for the GitHub repository and select ,,,</p> <p></p> <p>Select the Manual configuration as a <code>.circleci/config.yml</code> file has already been added to the Git repository.</p> <p></p> <p>Press Start Building button to confirm that a <code>config.yml</code> file has already been added and the build should start.</p> <p></p> <p>Now the first build runs with the <code>config.yml</code> file.</p> <p></p> <p>Its failed.  Okay lets investigate...</p> <p></p> <p>Thats okay, we have failing tests locally, so we know that the CircleCI build is working the same as on our local development environment.</p> <p>The continuous integration is now working and tests are automatically run as soon as you push changes to the remote repository.</p> <p>So the development of the project can continue with greater confidence</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#adding-a-build-status-badge","title":"Adding a Build Status badge","text":"<p>Generating a status badge documentation describes how to add a build status badge for your project, usually at the top of the README.md file in the project</p> <pre><code>[![CircleCI](https://circleci.com/gh/circleci/circleci-docs.svg?style=svg)](https://circleci.com/gh/practicalli/random-clojure-function)\n</code></pre> <p>Add this markdown to the top of the README.md file, underneath the title.  Then commit and push the change to the GitHub repository.</p> <p>NOTE: you might want to fix the unit tests first :)</p>"},{"location":"continuous-integration/circle-ci/status-monitor/","title":"Status Monitor Circle CI Continuous Integration","text":"<p>practicalli/webapp-status-monitor is a Leiningen project create in October 2018.</p> <p>The project uses ring and compojure as the basis of a web application.</p> <p>Configured with a project.clj file.</p> <pre><code>(defproject status-monitor \"0.1.0-SNAPSHOT\"\n  :description \"A server side website dashboard to collate monitoring information\"\n  :url \"https://github.com/jr0cket/status-monitor\"\n  :min-lein-version \"2.0.0\"\n  :dependencies [[org.clojure/clojure \"1.9.0\"]\n                 [compojure \"1.6.1\"]\n                 [ring/ring-defaults \"0.3.2\"]\n                 [hiccup \"1.0.5\"]]\n  :plugins [[lein-ring \"0.12.4\"]\n            [lein-eftest \"0.5.3\"]]\n  :ring {:handler status-monitor.handler/app}\n  :profiles\n  {:dev {:dependencies [[javax.servlet/servlet-api \"2.5\"]\n                        [ring/ring-mock \"0.3.2\"]]}})\n</code></pre>"},{"location":"continuous-integration/circle-ci/status-monitor/#circleci-configuration","title":"CircleCI Configuration","text":"<p>This configuration uses the CircleCI specific docker image with Java 17 and the latest version of Leiningen.</p> <p>The configuration defines that the code will be check out, Leiningen will download the dependencies and then run unit tests.</p> <pre><code>version: 2\njobs:\n  build:\n    docker:\n      - image: cimg/clojure:1.10\n\n    working_directory: ~/repo\n\n    environment:\n      LEIN_ROOT: \"true\"\n      # Customize the JVM maximum heap limit\n      JVM_OPTS: -Xmx3200m\n\n    steps:\n      - checkout\n\n      # Download and cache dependencies\n      - restore_cache:\n          keys:\n          - v1-dependencies-{{ checksum \"project.clj\" }}\n          # fallback to using the latest cache if no exact match is found\n          - v1-dependencies-\n\n      - run: lein deps\n\n      - save_cache:\n          paths:\n            - ~/.m2\n          key: v1-dependencies-{{ checksum \"project.clj\" }}\n\n      # run tests!\n      - run: lein test\n</code></pre>"},{"location":"continuous-integration/circle-ci/status-monitor/#caching-dependencies","title":"Caching dependencies","text":"<p>CircleCI create a cache of downloaded dependencies, to help speed up the running of the project.</p> <p>The config.yml defines the path where the dependencies are saved.  A unique key is used to identify the dependencies cache.</p> <p></p>"},{"location":"continuous-integration/github-workflow/","title":"GitHub Workflows","text":"<p>Automate tasks, such as running unit tests or lint code, whenever code is committed to a  GitHub repository.</p> <p>GitHub Actions can run one or more tasks after specific events, such as commits, raising issues or pull requests.</p> <p>An event triggers a configured workflow which contains one or more jobs. A job contains a one or more steps which defines actions to run.</p> <p>Practicalli GitHub Workflow Examples Practicalli recommended GitHub Actions</p> <p>Introduction to GitHub Actions Understanding the workflow file</p>"},{"location":"continuous-integration/github-workflow/#anatomy-of-a-workflow","title":"Anatomy of a workflow","text":"Term Description Event Triggers a workflow, e.g. Create pull request, push commit, etc. Workflow Top level configuration containing one or more jobs, triggered by a specific event Job Set of steps executed in the same runner, multiple jobs execute in parallel within their own instance of a runner Step Individual task that runs commands (actions), sharing data with other steps Action Standalone commands defined within a step, custom commands or GitHub community Runner A GitHub Actions server, listening for available jobs"},{"location":"continuous-integration/github-workflow/#example-github-action","title":"Example GitHub Action","text":"<p><code>.github/workflows/workflow-name.yaml</code> is a file that contains the workflow definition.</p> <p>Setup Java adds an OpenJDK distribution, i.e. Eclipse Temurin, at a specified version (Java 17 recommended).</p> <p>Setup Clojure provides Clojure via Clojure CLI, Leiningen or Boot.  Clojure CLI is recommended.</p> <p>Cache is used to cache Clojure and Java libraries</p> <ul> <li>The example workflow runs on Ubuntu.</li> <li>The project code is checked out from the Git repository.</li> <li>Java and Clojure run-times are added to the environment</li> <li>Unit tests are run using the <code>:test/run</code> alias (this alias should run Kaocha or similar test runner)</li> <li>Source code format and idioms are checked with cljstyle and clj-kondo</li> <li>The Clojure project is packaged into an Uberjar for deployment</li> </ul> <p>Example GitHub workflow for Clojure CLI project</p> <pre><code>name: Test and Package project\non:\n  pull_request:\n  push:\n    branches:\n      - main\njobs:\n  clojure:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Cache Clojure Dependencies\n        uses: actions/cache@v3\n        with:\n          path:\n            - ~/.m2\n            - ~/.gitlibs\n          key: cache-${{ hashFiles('**/deps.edn') }}\n          restore-keys: clojure-deps-\n\n      - name: Prepare java\n        uses: actions/setup-java@v3\n        with:\n          distribution: 'temurin'\n          java-version: '17'\n\n      - name: Install clojure tools\n        uses: DeLaGuardo/setup-clojure@9.5\n        with:\n          cli: 1.11.1.1165    # Clojure CLI based on tools.deps\n          cljstyle: 0.15.0 # cljstyle\n          clj-kondo: 2022.10.05 # Clj-kondo\n\n      - name: Run Unit tests\n        run: clojure -X:test/run\n\n      - name: \"Lint with clj-kondo\"\n        run: clj-kondo --lint deps.edn src resources test --config .clj-kondo/config-ci.edn\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - name: Package Clojure project\n        run: clojure -X:project/uberjar\n</code></pre>"},{"location":"continuous-integration/github-workflow/#references","title":"References","text":"<ul> <li>Practicalli Blog - publish blog workflow - build publish a Cryogen project with Clojure CLI and publish the generated website with GitHub pages (also a Staging workflow that runs on pull requests)</li> <li>Practicalli Landing Page GitHub workflow - build a ClojureScript &amp; Figwheel project with Clojure CLI and publish the generated site to GitHub pages</li> <li>Practicalli Clojure CLI config - lint with clj-kondo workflow - lint the <code>deps.edn</code> file with clj-kondo</li> </ul>"},{"location":"control-flow/cond/","title":"cond","text":""},{"location":"control-flow/if/","title":"if","text":""},{"location":"control-flow/when/","title":"when","text":""},{"location":"core.async/","title":"Introducing core.async","text":"<p>The <code>core.async</code> library provides a way to do concurrent programming using channels (eg. queues).</p> <p>It minimises the need to use complex concurrent constructs and worry less about thread management.</p> <p><code>core.async</code> is written in Clojure and can be used with both Clojure and ClojureScript.</p> <ul> <li>core.async getting started</li> <li>Introduction to asynchronous programming</li> <li>ClojureScript core.async and todos - Bruce Haurman</li> <li>core.async 101</li> <li>Mastering concurrent processes</li> <li>LispCast Clojure core.async: Channels - first lesson only.</li> <li>core.async introduction in ClojureScrpt unravelled</li> <li>core.async: Concurrency without Callbacks - Stuart Halloway</li> <li>David Nolan - core.async for asynchronous programming</li> <li>Timothy Baldridge - Core.Async</li> <li>core.async in Use - Timothy Baldridge</li> <li>Timothy Baldridge - core.async - pipelines - free video</li> <li>Timothy Baldridge - core.async - garbage collected go blocks - free video</li> </ul>"},{"location":"core.async/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/#hint-coreasync-resources","title":"Hint:: core.async resources","text":""},{"location":"core.async/#hintcommunicating-sequential-processes","title":"Hint::Communicating Sequential Processes","text":"<p>Communicating Sequential Processes (CSP) is a formalism for describing concurrent systems pioneered by C. A. R. Hoare in 1978. It is a concurrency model based on message passing and synchronization through channels</p>"},{"location":"core.async/#coreasync-on-clojurescript","title":"core.async on ClojureScript","text":"<p>core.async is very widely used within ClojureScript applications and many libraries are built on top of it.</p> <p>It\u2019s a good example of the syntactic abstractions that can be achieved by transforming code with ClojureScript macros.</p> <p>JavaScript is single-threaded so you do not get the benefit of safe communication between threads, as there is only one.</p>"},{"location":"core.async/#concepts","title":"Concepts","text":""},{"location":"core.async/#channels","title":"Channels","text":"<p>A channel is a queue with one or more publishers and one or more consumers.  Producers put data onto the queue, consumers take data from the queue.</p> <p>As data in Clojure is immutable, channels provide a safe way to communicate between threads.</p>"},{"location":"core.async/#chanel-size","title":"Chanel size","text":"<p>Channels do not include a buffer by default,  they use a producer (<code>put!</code>) and consumer (<code>take!</code>) to transfer a value through the channel.  A maximum of 1024 <code>put!</code> functions can be queued onto a single channel.</p> <p>Specify a channel using <code>(chan)</code> or a channel with a fixed buffer using <code>(chan 12)</code>.</p>"},{"location":"core.async/#processes","title":"Processes","text":"<p>Processes are independently running pieces of code that use channels for communication and coordination.</p> <p>Calling <code>put!</code> and <code>take!</code> inside a process will stop that process until the operation completes.</p> <p>Processes are launched using the go macro and puts and takes use the &lt;! and &gt;! placeholders. The go macro rewrites your code to use callbacks but inside go everything looks like synchronous code, which makes understanding it straightforward:</p> <p>In ClojureScript, stopping a process doesn\u2019t block the single-threaded JavaScript environment, instead, the process will be resumed at a later time when it is no longer blocked.</p>"},{"location":"core.async/#important-functions","title":"Important functions","text":""},{"location":"core.async/#chan","title":"<code>chan</code>","text":"<p>The <code>chan</code> function creates a new channel.</p> <p>You can give a name to a channel using the <code>def</code> function, eg. <code>(def my-channel (chan))</code></p> <p>A single channel can take a maximum of 1024 put requests.  Once it has reached the maximum, then it is considered full.</p> <p>A buffer of a fixed size can be specified when defining a new channel: <code>(def channel-with-fixed-buffer (chan 12))</code>.  This buffer increases the number of puts that can be sent to the channel.  A dropping or sliding buffer can be used to discard messages added when the buffer is full.</p> <p>A channel can also include a transducer, to manipulate the value on the channel eg. adding a timestamp <code>(chan 32 (map (Date. now)))</code> eg. filtering messages <code>(chan 12 (map even?))</code></p> <p>Channels can be explicitly closed using <code>(close channel-name)</code> or by adding a timeout that closes the channel after the specified number of milliseconds <code>(timeout 6000)</code>.</p>"},{"location":"core.async/#put","title":"<code>put!</code>","text":"<p>The <code>put!</code> function puts a value (message) on the channel.</p> <p>You can put messages on the channel even if nothing is listening (no waiting <code>take!</code> functions).</p> <p>Evaluating <code>put!</code> will always add a message on to the channel as long as the channel is open and not full.</p>"},{"location":"core.async/#take","title":"<code>take!</code>","text":"<p>The <code>take!</code> function will take a single message from the queue.</p> <p>If there are no messages on the queue when you evaluate <code>take!</code>, then the function will wait to execute as soon as something is put on the channel</p> <p>The <code>take!</code> function needs an argument that is the channel and a function that will receive any message taken from a channel.</p>"},{"location":"core.async/#time","title":"<code>time</code>","text":"<p>This is a macro that executes an expression and prints the time it takes</p> <p>Criterium is an excellent library for performance testing your code</p>"},{"location":"core.async/#go","title":"<code>go</code>","text":"<p>Referred to as a go block, the <code>go</code> function creates a lightweight process, not bound to threads.  Thousands of go blocks can be created efficiently and they can all have their own channel.</p>"},{"location":"core.async/#blocking-and-non-blocking","title":"blocking and non-blocking","text":"<p>core.async offers two ways to write to and read from channels: blocking and non-blocking. A blocking write blocks the thread until the channel has space to be written to (the buffer size of a channel is configurable), a blocking read blocks a thread until a value becomes available on the queue to be read.</p> <p>More interesting, and the only type supported in ClojureScript, are asynchronous channel reads and writes to channels, which are only allowed in \"go blocks\". Go blocks are written in a synchronous style, and internally converted to a state machine that executes them asynchronously.</p> <p>Consider the following core.async-based code:</p> <pre><code>(let [ch (chan)]\n  (go (while true\n        (let [v (&lt;! ch)]\n          (println \"Read: \" v))))\n  (go (&gt;! ch \"hi\")\n      (&lt;! (timeout 5000))\n      (&gt;! ch \"there\")))\n</code></pre> <p>In this example, let introduces a new local variable ch, which is a new channel. Within the let's scope two go blocks are defined, the first is an eternal loop that reads (&lt;!) a new value from channel ch into variable v. It then prints \"Read: \" followed by the read value to the standard out. The second go block writes (&gt;!) two values to channel ch: \"hi\", it then waits 5 seconds and then writes \"there\" to the channel. Waiting for 5 seconds is implemented by reading from a timeout channel, which is a channel that closes itself (returns nil) after a set timeout. When running this code in the Clojure REPL (for instance), it will return instantly. It will then print \"Read: hi\", and 5 seconds later it will print \"Read: there\".</p>"},{"location":"core.async/#hint","title":"Hint::","text":"<p>In JavaScript you cannot do blocking loops like this: the browser will freeze up for 5 seconds. The \"magic\" of core.async is that internally it converts the body of each go block into a state machine and turns the synchronous-looking channel reads and writes into asynchronous calls.</p>"},{"location":"core.async/bike-assembly-line/","title":"core.async scenario: Bike assembly line","text":"<p>In this example we are going to use a bicycle assembly line as the process we want to make concurrent.  The tasks involved in making our bicycle are:</p> <ul> <li>Making the frame</li> <li>Painting the wheels</li> <li>Making the rims</li> <li>Making the wheels (adding hub and spokes to wheels - different hub for front and rear wheels)</li> <li>Making the handlebars</li> <li>Fitting tyres to the rims (solid rims, so no tubes)</li> <li>Attaching the handlebars to the frame</li> <li>Attaching wheels to the frame</li> <li>Attaching crank to frame</li> <li>Attaching peddles to the crank</li> <li>Connecting control system wires (gears, breaks)</li> </ul>"},{"location":"core.async/bike-assembly-line/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/bike-assembly-line/#current-build-process","title":"Current build process","text":"<p>At the moment, each person creates one bicycle all by themselves.  This means they need all sorts of different tools and are switching tasks all the way through assembling the bike.</p> <p>We want to move to a more parallel approach, so as we automate this process we will evaluate what actions can be done in parallel and which must be done sequentially (i.e. painting the frame must come after making the frame).</p>"},{"location":"core.async/clacks-messages/","title":"Clacks Messenger with core.async","text":"<p>In a previous exercise we built a simple encoder/decoder to send messages via the Clacks message service (as designed by Sir Terry Pratchett, RIP).</p> <p>Now we will use core.async to create a processing queue between each Clack towers, so we can then model, monitor and visualise a Clacks messenger system with multiple Clacks towers.  For additional fun we will enable new Clacks towers to come on line and connect to the existing system.</p>"},{"location":"core.async/clacks-messages/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/toy-car-assembly-line/","title":"core.async example - toy car assembly line","text":""},{"location":"core.async/toy-car-assembly-line/#noteget-the-example-project-and-open-it-in-a-clojure-repl","title":"Note::Get the example project and open it in a Clojure REPL","text":"<p>Clone or download the Lispcast: Clojure core-async Factory example</p> <p>Open that project in your Clojure editor or run <code>lein repl</code> in the top level directory of the project.</p>"},{"location":"core.async/toy-car-assembly-line/#the-toy-car-factory","title":"The toy car factory","text":"<p>The toy car factory assembles car parts before distributing them.  How can we make this process faster and more scalable?</p>"},{"location":"core.async/toy-car-assembly-line/#the-current-process","title":"The current process","text":"<p>One worker picks out random parts of a car from the parts box until all the parts are collected to assemble the car.</p>"},{"location":"core.async/toy-car-assembly-line/#the-time-macro","title":"The <code>time</code> macro","text":"<p>We will use the time macro to see how long parts of our code takes to run and help find parts to optimise.</p> <p>A simple example would be:</p> <pre><code>(time\n  (map inc (range 0 10000)))\n</code></pre>"},{"location":"core.async/toy-car-assembly-line/#timing-assembly-functions","title":"Timing assembly functions","text":"<p>Investigate the time it takes to carry out the different assembly line tasks</p> <pre><code>(time (take-part))\n\n(time (attach-wheel :body :wheel))\n\n(time (box-up :body))\n\n(time (put-in-truck :body))\n</code></pre> <p>And to total time it takes to get a a whole car through the assembly line</p> <pre><code>(time (build-car))\n</code></pre> <p>The total time can be longer than the sum of the tasks, as the <code>take-part</code> function does not always give the required part needed.</p>"},{"location":"core.async/toy-car-assembly-line/#hiring-more-workers","title":"Hiring more workers","text":"<p>Adding 10 more workers is equivalent to adding 10 processes that run the assembly tasks.</p> <p>Lets use a go block for a worker</p> <pre><code>(do\n  (go\n    (dotimes [number 10]\n      (println \"First go block processing:\" number)\n      (Thread/sleep 1200)))\n  (go\n    (dotimes [number 10]\n      (println \"Second go block processing:\" number)\n      (Thread/sleep 1200))))\n</code></pre> <p>These are two separate go blocks, so their is no co-ordination between the two.  You can see the println statement from each go block intertwined.</p>"},{"location":"data-inspector/","title":"Clojure Data Browsers","text":"<p>Clojure has a strong focus on using the built in data structures (list, vector, hash-map, set) to represent information in the system.  Tools to inspect data and browse through nested or large data sets is invaluable in understanding what the system is doing.</p> <p>There are many <code>clojure.core</code> functions that can be used to explore data structures and transform them to produce specific views on data.</p> <p><code>tap&gt;</code> and <code>datafy</code> are recent additions to Clojure that provide a more elegant way of exploring data than the classic <code>println</code> statement.</p> <p>New tools are being created to capture and visualize results from evaluated expressions (REBL, Reveal) as well as tools to specifically visualize <code>tap&gt;</code> expressions (Reveal, Portal).</p>"},{"location":"data-inspector/#common-approaches","title":"Common approaches","text":"<ul> <li>Editor data browsers - e.g. cider-inspect</li> <li>Portal - tool to navigate and visualise data via <code>tap&gt;</code></li> <li>Clojure inspector - built-in Java Swing based inspector</li> <li>Reveal repl with data browser, also a <code>tap&gt;</code> source (semi-commercial project)</li> </ul>"},{"location":"data-inspector/clojure-inspector/","title":"Clojure Inspector","text":"<p>A visual browser for Clojure data using the Java UI libraries.</p> <p>Require the <code>clojure.inspector</code> namespace in the REPL or project namespace definitions to use the functions</p> ReplProject <pre><code>(require '[clojure.inspector :as inspector])\n</code></pre> <pre><code>(ns practicalli.application\n  (:require [clojure.inspector :as inspector]))\n</code></pre> <ul> <li><code>inspect</code> for flat data structures</li> <li><code>inspect-tree</code> for deeply nested / hierarchically data</li> <li><code>inspect-table</code> a sequence of data structures with the same shape</li> </ul>"},{"location":"data-inspector/clojure-inspector/#inspect","title":"<code>inspect</code>","text":"<p>View flat structures especially with non-trivial size data sets.</p> <p>This example generated 10,000 random numbers.  The Clojure inspector shows the values along with their index in the collection.</p> <pre><code>(inspector/inspect\n  (repeatedly 10000 #(rand-int 101)))\n</code></pre> <p></p>"},{"location":"data-inspector/clojure-inspector/#inspect-tree","title":"<code>inspect-tree</code>","text":"<pre><code>(inspect\n  {:star-wars\n    {:characters\n      {:jedi [\"obiwan kenobi\" \"Yoda\" \"Master Wendoo\"]\n       :sith [\"Palpatine\" \"Count Dukoo\"]}}})\n</code></pre>"},{"location":"data-inspector/clojure-inspector/#inspect-table","title":"<code>inspect-table</code>","text":"<p>Inspect a sequence of data structures that share the same form, often found in data sets for machine learning and wider data science, eg. daily weather records.</p> <p>This example generates mock data for a 20 day period for one or more locations.  Each day contains the day, location and cumulative number of cases reported.</p> <pre><code>(defn mock-data-set\n  \"Generates a set of mock data for each name\n  Arguments: names as strings, names used in keys\n  Returns: Sequence of maps, each representing confirmed cases\"\n  [&amp; locations]\n  (for [location locations\n        day      (range 20)]\n    {:day      day\n     :location location\n     :cases    (+ (Math/pow (* day (count location)) 0.8)\n                  (rand-int (count location)))}))\n\n(inspector/inspect-table\n  (mock-data-set \"England\" \"Scotland\" \"Wales\" \"Northern Ireland\"))\n</code></pre> <p></p>"},{"location":"data-inspector/portal/","title":"Portal - navigate your data","text":"<p>Portal inspector is a tool for exploration of Clojure data using a browser window to visualise and inspect Clojure, JSON, Transit, Logs, Yaml, etc.</p> <p>Registered Portal as a tap source and wrap code with <code>(tap&gt; ,,,)</code> to see the results in Portal, providing a more advanced approach to debuging than println.</p> <p>Send all evaluation results to Portal for a complete history using the portal-wrap nREPL middleware</p> <p>Add a custom Mulog publisher to send all logs to Portal to help with debugging.</p> <p>Open Portal from the REPL or configure Portal to open on REPL startup.</p> <p>Practicalli Project Templates</p> <p>Clojure projects created with Practicalli Project Templates include Portal configuration to recieve all evaluation results and Mulog event logs.</p> <p>A custom <code>dev/user.clj</code> file loads <code>dev/portal.clj</code> and <code>dev/mulog-events.clj</code> configurations on REPL startup, when the <code>dev</code> directory is included on the path.</p> <p>Use the <code>:repl/reloaded</code> for a complete REPL reloaded workflow and tooling on REPL startup</p> <p></p> Clojure 1.10 onward required tap sources and tap&gt; <p>tap is a shared, globally accessible system for distributing values (log, debug, function results) to registered tap sources.</p> <p><code>add-tap</code> to register a source and receive all values sent. <code>remove-tap</code> to remove a source.</p> <p><code>tap&gt;</code> form sends its contents to all registered taps. If no taps are registered, the values sent by tap&gt; are discarded.</p> <p><code>(deref (deref #'clojure.core/tapset))</code> will show the tap sources. <code>tapset</code> is a Clojure set defined as private var and not meant to be accessed directly.</p> <p>Online Portal demo</p>"},{"location":"data-inspector/portal/#add-portal","title":"Add Portal","text":"<p>Clojure CLI user configuration aliases enable Portal to be used with any Clojure or ClojureScript project.</p>  Practicalli Clojure CLI ConfigAlias Definition <p> Practicalli Clojure CLI Config contains several aliases that support Portal, either to start a REPL process that can send all Clojure evaluated code to Portal or simply adding Portal as a library for manual use.</p> <p>Run a REPL with portal and <code>portal.nrepl/wrap-portal</code> to send every REPL evaluation to Portal over an nREPL connection</p> <ul> <li><code>:repl/reloaded</code> - starts a rich terminal UI REPL with Portal nREPL middleware, including REPL Reloaded tools</li> <li><code>:repl/inspect</code> - starts a basic REPL with Portal nREPL middleware.</li> </ul> <p>Or include the portal library in <code>clojure</code> commands or when starting a REPL via an editor</p> <ul> <li><code>dev/reloaded</code> - Portal, including REPL Reloaded tools</li> <li><code>inspect/portal-cli</code> - Clojure CLI (simplest approach)</li> <li><code>inspect/portal-web</code> - Web ClojureScript REPL</li> <li><code>inspect/portal-node</code> - node ClojureScript REPL</li> </ul> <p>Create portal aliases to include the portal libraries for the Clojure, ClojureScript Web browser and ClojureScript Node server libraries</p> <p>Portal aliases in Clojure CLI user configuration</p> <pre><code>:inspect/portal-cli\n{:extra-deps {djblue/portal {:mvn/version \"0.34.2\"}\n              clj-commons/clj-yaml         {:mvn/version \"0.7.0\"}}}\n\n:inspect/portal-web\n{:extra-deps {djblue/portal             {:mvn/version \"0.34.2\"}\n              org.clojure/clojurescript {:mvn/version \"1.10.844\"}}\n :main-opts  [\"-m\" \"cljs.main\"]}\n\n:inspect/portal-node\n{:extra-deps {djblue/portal             {:mvn/version \"0.34.2\"}\n              org.clojure/clojurescript {:mvn/version \"1.10.844\"}}\n :main-opts  [\"-m\" \"cljs.main\" \"-re\" \"node\"]}\n\n:repl/inspect\n{:extra-deps\n {cider/cider-nrepl {:mvn/version \"0.28.5\"}\n  djblue/portal     {:mvn/version \"0.33.0\"}\n  clj-commons/clj-yaml         {:mvn/version \"0.7.0\"}}\n :main-opts [\"-m\" \"nrepl.cmdline\"\n             \"--middleware\"\n             \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"]}\n</code></pre> <p> Practicalli Clojure CLI Config contains several aliases that support Portal.</p> YAML support for Portal - Clojure only <p> clj-commons/clj-yaml adds YAML support to Portal for Clojure on the JVM</p> <p>REPL Reloaded Aliases</p> <p> REPL Reloaded section includes the <code>:repl/reloaded</code> and <code>:dev/reloaded</code> ailas definitions</p>"},{"location":"data-inspector/portal/#start-repl-with-portal","title":"Start REPL with Portal","text":"<p>Run a REPL in a terminal and include the Portal library, using the Clojure CLI tools</p> REPL StarupEmacs Project configurationEmacs variable <p>Start a REPL with namespace reloading, hotload libraries and portal data inspector</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Or start the REPL with only portal</p> <pre><code>clojure -M:inspect/portal:repl/rebel\n</code></pre> <p>Add <code>cider-clojure-cli-aliases</code> to a <code>.dir-locals.el</code> in the root of the Clojure project with an alias used to add portal</p> <p>.dir-locals.el</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":dev/reloaded\"))))\n</code></pre> <p>Or include an alias with only portal data inspector</p> <p>.dir-locals.el</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":inspect/portal-cli\"))))\n</code></pre> <p>Set <code>cider-clojure-cli-aliases</code> to the alias used to add portal, e.g. <code>inspect/portal</code></p> <p>Example</p> <pre><code>(setq cider-clojure-cli-aliases \":inspect/portal\")\n</code></pre> <p>Spacemacs: add to <code>dotspacemacs/user-config</code> in the Spacemacs configuration file.  Doom Emacs: add to <code>config.el</code> Doom configuration file.</p>"},{"location":"data-inspector/portal/#open-portal","title":"Open Portal","text":"<p><code>(require '[portal.api :as inspect])</code> once the REPL starts.</p> <p>For <code>inspector-portal-web</code> use <code>(require '[portal.web :as inspect])</code> instead</p> <p><code>(inspect/open)</code> to open the Portal inspector window in a browser (see portal themes)</p> <p><code>(add-tap #'portal/submit)</code> to add portal as a tap target</p>"},{"location":"data-inspector/portal/#use-portal-from-repl","title":"Use Portal from REPL","text":"<p>Portal functions can be called from the REPL prompt. When using Portal regularly, include code in a file, e.g. <code>dev/user.clj</code>  namespace to start a portal and add a tap source.  Use a rich comment form, <code>(comment ,,,)</code> to wrap the portal function calls if Portal should be launched manually by the developer.</p> <p>user namespace and REPL commands</p> <pre><code>(ns user\n  (:require [portal.api :as inspect]))\n\n(comment\n  ;; Open a portal inspector window\n  (inspect/open)\n  ;; Add portal as a tap&gt; target over nREPL connection\n  (add-tap portal.api/submit)\n  ;; Clear all values in the portal inspector window\n  (inspect/clear)\n  ;; Close the inspector\n  (inspect/close)\n  ) ;; End of rich comment block\n</code></pre>"},{"location":"data-inspector/portal/#open-portal-on-repl-startup","title":"Open Portal on REPL startup","text":"<p>Start the Portal inspector as soon as the REPL is started.  This works for a terminal REPL as well as clojure aware editors.</p> <p>Create a <code>dev/user.clj</code> source code file which requires the portal.api library, opens the inspector window and adds portal as  a tap source.</p> REPL ReloadedBasic Portal config <p>When using namespace reloading tools (clojure tools.namespace.repl, Integrant, etc.) it is advisable to exclude <code>dev</code> directory from the path to avoid launching multiple instances of Portal.</p> <p>Example</p> <pre><code>(ns user\n  (:require\n   [portal.api :as inspect]\n   [clojure.tools.namespace.repl :as namespace]))\n\n(println \"Set REPL refresh directories to \" (namespace/set-refresh-dirs \"src\" \"resources\"))\n</code></pre> <p>As a further precaution, check the Portal API <code>sessions</code> value to ensure Portal is not already running, preventing Portal running multiple times</p> <p>Example</p> <pre><code>(def portal-instance\n  (or (first (inspect/sessions))\n      (inspect/open {:portal.colors/theme :portal.colors/gruvbox})))\n</code></pre> <p>Example</p> <pre><code>(ns user\n  (:require [portal.api :as inspect]))\n\n;; ---------------------------------------------------------\n;; Open Portal window in browser with dark theme\n(inspect/open {:portal.colors/theme :portal.colors/gruvbox})\n;; Add portal as a tap&gt; target over nREPL connection\n(add-tap #'portal.api/submit)\n;; ---------------------------------------------------------\n(comment\n  (inspect/clear)  ; Clear all values in the portal inspector window\n  (inspect/close)  ; Close the inspector\n  ) ; End of rich comment block\n</code></pre> <p>Start a REPL using the <code>:repl/reloaded</code> or <code>:dev/reloaded</code> alias from  Practicalli Clojure CLI Config to include the <code>dev</code> directory on the path and the portal library.</p>"},{"location":"data-inspector/portal/#basic-use","title":"Basic use","text":"<p>The <code>tap&gt;</code> function sends data to Portal to be shown on the inspector window.</p> <pre><code>(tap&gt; {:accounts\n        [{:name \"jen\" :email \"jen@jen.com\"}\n        {:name \"sara\" :email \"sara@sara.com\"}]})\n</code></pre> <p>Use portal to navigate and inspect the details of the data sent to it via <code>tap&gt;</code>.</p> <p><code>(inspect/clear)</code> to clear all values from the portal inspector window.</p> <p><code>(inspect/close)</code> to close the inspector window.</p>"},{"location":"data-inspector/portal/#editor-commands","title":"Editor Commands","text":"<p>Control Portal from a Clojure Editor by wrapping the portal commands.</p> Emacs <p>Add helper functions to the Emacs configuration and add key bindings to call them.</p> <p>Emacs Configuration</p> <pre><code>;; def portal to the dev namespace to allow dereferencing via @dev/portal\n(defun portal.api/open ()\n  (interactive)\n  (cider-nrepl-sync-request:eval\n    \"(do (ns dev)\n         (def portal ((requiring-resolve 'portal.api/open)))\n         (add-tap (requiring-resolve 'portal.api/submit)))\"))\n\n(defun portal.api/clear ()\n  (interactive)\n  (cider-nrepl-sync-request:eval \"(portal.api/clear)\"))\n\n(defun portal.api/close ()\n  (interactive)\n  (cider-nrepl-sync-request:eval \"(portal.api/close)\"))\n</code></pre> <ul> <li>Spacemacs: add to <code>dotspacemacs/user-config</code> in the Spacemacs configuration file.</li> <li>Doom emacs: add to <code>config.el</code> Doom configuration file.</li> </ul> <p>Add key bindings to call the helper functions, ideally from the Clojure major mode menu.</p> SpacemacsDoom Emacs <p>Add key bindings specifically for Clojure mode, available via the <code>, d p</code> debug portal menu when a Clojure file (clj, edn, cljc, cljs) is open in the current buffer.</p> <p>Spacemacs Key bindings for Portal</p> <p>Add key bindings to Clojure major mode, e.g. , d p c to clear values from Portal Spacemacs Configuration - dotspacemacs/user-config<pre><code>(spacemacs/declare-prefix-for-mode 'clojure-mode \"dp\" \"Portal\")\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpp\" 'portal.api/open)\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpc\" 'portal.api/clear)\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpD\" 'portal.api/close)\n</code></pre></p> <p>Or add user key bindings to user menu, <code>SPC o</code> avoiding potential clash with Spacemacs Clojure layer key bindings. e.g. Space o p c to clear values from Portal Spacemacs Configuration - dotspacemacs/user-config<pre><code>(spacemacs/declare-prefix \"op\" \"Clojure Portal\")\n(spacemacs/set-leader-keys \"opp\" 'portal.api/open)\n(spacemacs/set-leader-keys \"opc\" 'portal.api/clear)\n(spacemacs/set-leader-keys \"opD\" 'portal.api/close)\n</code></pre></p> <p>Use the <code>map!</code> macro to add keys to the <code>clojure-mode-map</code>, using <code>:after</code> to ensure cider is loaded before binding the keys</p> <p>Doom Configuration</p> <pre><code>(map! :map clojure-mode-map\n      :n \"s-o\" #'portal.api/open\n      :n \"C-l\" #'portal.api/clear)\n</code></pre> <p>Practicalli Doom Emacs configuration</p> <p>Practicalli Doom Emacs config includes Portal key bindings in the Clojure major mode menu, under the debug menu. * <code>, d p o</code> to open portal * <code>, d p c</code> to clear results from portal</p> <pre><code>(map! :after cider\n      :map clojure-mode-map\n      :localleader\n      :desc \"REPL session\" \"'\" #'sesman-start\n\n      ;; Debug Clojure\n      (:prefix (\"d\" . \"debug/inspect\")\n       :desc \"debug\" \"d\" #'cider-debug-defun-at-point\n       (:prefix (\"i\" . \"inspect\")\n        :desc \"last expression\" \"e\" #'cider-inspect-last-sexp\n        :desc \"expression\" \"f\" #'cider-inspect-defun-at-point\n        :desc \"inspector\" \"i\" #'cider-inspect\n        :desc \"last result\" \"l\" #'cider-inspect-last-result\n        (:prefix (\"p\" . \"portal\")\n         :desc \"Clear\" \"c\" #'portal.api/clear\n         :desc \"Open\" \"D\" #'portal.api/close\n         :desc \"Open\" \"p\" #'portal.api/open)\n        :desc \"value\" \"v\" #'cider-inspect-expr))\n\n        ; truncated...\n        )\n</code></pre> <p>Practicalli Doom Emacs Config - +clojure.el</p> <p>Portal Documentation - Editors</p>"},{"location":"data-inspector/portal/#editor-nrepl-middleware","title":"Editor nREPL middleware","text":"<p><code>portal.nrepl/wrap-portal</code> sends every REPL evaluation to Portal over an nREPL connection, avoiding the need to wrap expressions with <code>tap&gt;</code>.</p>  Practicalli Clojure CLI ConfigAlias Definition <p>Start a REPL that includes the Portal nREPL middleware to send the result of every evaluation to portal.</p> <ul> <li><code>:repl/reloaded</code> - rich terminal UI with portal and REPL Reloaded tools</li> <li><code>:repl/inspect</code> - basic terminal UI with portal</li> </ul> <p><code>:repl/inspect</code> to start a terminal REPL with nREPL support for Clojure editor connection and portal libraries and middleware that will send all evaluations to portal once added as a tap source. !!!! EXAMPLE \"User deps.edn\"     <pre><code>:repl/inspect\n{:extra-deps\n {nrepl/nrepl          {:mvn/version \"1.0.0\"}\n  cider/cider-nrepl    {:mvn/version \"0.30.0\"}\n  djblue/portal        {:mvn/version \"0.40.0\"}\n  clj-commons/clj-yaml {:mvn/version \"0.7.0\"}}\n :main-opts [\"-m\" \"nrepl.cmdline\"\n             \"--middleware\"\n             \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"]}\n</code></pre></p> <p>Start a REPL with <code>:repl/reloaded</code> or 'repl/inspect'</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Start Portal User Interface and add portal as a tap target using the <code>portal.api/submit</code> function to send all evaluated code to Portal</p> <p>Clear results to keep history manageable</p> <p>Use the Portal API <code>clear</code> function to remove all existing results in Portal</p>"},{"location":"data-inspector/portal/#tap-logs-to-portal","title":"Tap Logs to Portal","text":"<p>Using a custom mulog publisher, all event logs can be automatically sent to portal.</p> <p>mulog tap publisher</p> <pre><code>;; ---------------------------------------------------------\n;; Mulog Custom Publishers\n;; - tap publisher for use with Portal and other tap sources\n;; ---------------------------------------------------------\n(ns mulog-publisher\n  (:require\n   ;; [com.brunobonacci.mulog :as mulog]\n   [com.brunobonacci.mulog.buffer :as mulog-buffer]\n   [portal.api :as p]))\n\n(deftype TapPublisher [buffer transform]\n  com.brunobonacci.mulog.publisher.PPublisher\n  (agent-buffer [_] buffer)\n  (publish-delay [_] 200)\n  (publish [_ buffer]\n    (doseq [item (transform (map second (mulog-buffer/items buffer)))]\n      (tap&gt; item))\n    (mulog-buffer/clear buffer)))\n\n(defn tap\n  [{:keys [transform] :as _config}]\n  (TapPublisher. (mulog-buffer/agent-buffer 10000) (or transform identity)))\n</code></pre> <p>Require the <code>mulog-publisher</code> namespace and mulog library in the <code>user</code> ns expression</p> <p>Require <code>mulog-publisher</code> namespace</p> <pre><code>(ns user\n  \"Tools for REPL Driven Development\"\n  (:require\n   [com.brunobonacci.mulog :as mulog]\n   [mulog-publisher]))\n</code></pre> <p>Start the publisher, optionally setting a global context for events first</p> <p>Set values for all mulog events and start custom mulog publisher</p> <pre><code>;; ---------------------------------------------------------\n;; Mulog events and publishing\n\n;; set event global context - information added to every event for REPL workflow\n(mulog/set-global-context! {:app-name \"Practicalli Service\",\n                            :version \"0.1.0\", :env \"dev\"})\n\n(def mulog-tap-publisher\n  \"Start mulog custom tap publisher to send all events to Portal\n  and other tap sources\n  `mulog-tap-publisher` to stop publisher\"\n  (mulog/start-publisher!\n    {:type :custom, :fqn-function \"mulog-publisher/tap\"}))\n;; ---------------------------------------------------------\n</code></pre> <p>Mulog events are now sent to portal when evaluated</p> <pre><code>    (mulog/log ::repl-state ::ns (ns-publics *ns*))\n</code></pre> <p>Stop the mulog publisher by calling the reference it returns, i.e. mulog-tap-publisher</p> <p>Function to stop mulog tap publisher</p> <pre><code>(defn mulog-tap-stop\n \"Stop mulog tap publisher to ensure multiple publishers are not started\n Recommended before using `(restart)` or evaluating the `user` namespace\"\n  [] (mulog-tap-publisher))\n</code></pre>"},{"location":"data-inspector/portal/#references","title":"References","text":"<p> Portal Documentation - clj-docs</p>"},{"location":"data-structures/","title":"Data structures","text":"<p>Clojure is a very data-centric language.  <code>clojure.core</code> contains a great number of functions for manipulating data structures, especially the immutable built in data structures, referred to generically as collections.</p> <p>Collections can take any types of elements and types can be mixed.  Collections can even have other collections as an element.</p> <p>Collections are passed as arguments to function (either in part or in full) and functions often return collections as a result.</p>"},{"location":"data-structures/#built-in-collections","title":"Built-in collections","text":"<p>Values can be represented as a collection of discrete pieces of data: number, string, boolean value.</p> <p>Clojure has great facilities for working with collections of data, providing many types of data structures and a uniform way to use all of these data structures.</p> <p>The 4 commonly used built-in data structures</p> Name syntax Description list <code>()</code> A linked list, optomised for sequential access from the front (head) vector <code>[]</code> An indexed array optimised for random access hash-map <code>{:key \"value\"}</code> Associative collection of key / value pairs, keys must be unique. Keys are the index set <code>#{}</code> A unique set of values <p>Vector and hash-map are the most commonly collections used to model information with Clojure.</p> <p>Lists are not explicitly used to model data, although data may be returned by a function as a list (referred to as a sequence)</p>"},{"location":"data-structures/#collection-characteristics","title":"Collection Characteristics","text":"<p>Clojure data structure share the following characteristics:</p> <ul> <li>Immutable - once a data structure is defined it cannot be changed</li> <li>Persistent - functions may return an altered copy of a data structure which will share common values with the original data structure for efficient memory use (structural sharing)</li> <li>Dynamically typed - a data structure can contain any value, including functions (as they evaluate to a value) and other data structures (nested data structures)</li> </ul> <p>This section will cover the Clojure built in persistent data structures in more detail.</p>"},{"location":"data-structures/#common-data-structures","title":"Common Data Structures","text":"<p>Simple data</p> <p>(def name value)</p> <p>Sequential data</p> <p>(list ...) sequence - always processed sequentially</p> <p>(vector) sequencw with randon access</p> <p>Dictionary</p> <p>(key value  key1 value  key2 value)</p> <p>Connverting data, data decoder/encoder, state machine, etc</p> <p>Data set</p> <pre><code>(def name\n  [{:identical-keys \"with evolving values\"}\n   {:identical-keys \"values differ from each other\"}\n   {:identical-keys \"values collectively provide meaning\"}])\n</code></pre> <p>Weather monitoring data, bank transactions, stock exchange rates, etc</p>"},{"location":"data-structures/#hierarchical-data","title":"Hierarchical data","text":"<pre><code>(def name\n  {:simple-key value\n   :composite-key {:nested-key value}\n   :deeper-composite-key {:nested-key {:deeper-nested-key value}}})\n</code></pre> <p>representing state, structure of a website Starwars example,</p> <p>walk the hierarchy to get the appropriate values</p> <p>extract only the values required by a function and pass as arguments</p> <p>hierachiecy can become too complex to manage, the flatest possible structure is usually simpler to work with (transform)</p>"},{"location":"data-structures/alternatives/","title":"Alternative data structures","text":"<p>Whist list, vector, hash-map and set are by far the most commonly used data structures, Clojure has many others of interest.</p>"},{"location":"data-structures/alternatives/#variations-on-hash-maps","title":"Variations on hash-maps","text":""},{"location":"data-structures/alternatives/#variations-on-sets","title":"Variations on sets","text":"<p>ordered-set</p>"},{"location":"data-structures/list/","title":"List","text":"<p>The list is used extensively in Clojure, it is a List (List Processing) language after all.  The unique thing about lists is that the first element is always evaluated as a function call, therefore lists are most commonly used for defining and calling functions.</p> <p>Lists are sometimes used as a data structure and have a sequential lookup time.  A list can hold any valid types of data, from numbers and strings to other data structures such as vectors, maps and sets.  Types can be mix as Clojure will dynamically type each element as its evaluated.</p> <p>Its more common to use vectors and maps which typically offer quicker access as they can be looked up via an index or key.</p> <p>Note Explore the list data structure and discover which line of code fails.  Try work out why that line of code fails.</p> <pre><code>(list 1 2 3 4)\n(list -1 -0.234 0 1.3 8/5 3.1415926)\n(list \"cat\" \"dog\" \"rabbit\" \"fish\")\n(list :cat 1 \"fish\" 22/7 (str \"fish\" \"n\" \"chips\"))\n(list 1 2 \"three\" [4] five '(6 7 8 9))\n(list )\n\n( 1 2 3 4)\n\n(quote (1 2 3 4))\n'(1 2 3 4)\n\n;; Duplicate elements in a list ?\n(list 1 2 3 4 1)\n(list \"one\" \"two\" \"one\")\n(list :fred :barney :fred)\n</code></pre> <p>We can create a list using the <code>list</code> function</p> <pre><code>(list 1 2 3 4)\n</code></pre> <p>This evaluates to <code>(1 2 3 4)</code></p> <p>We can give this result a name</p> <pre><code>(def my-list (list 1 2 3 4))\n</code></pre> <p>Then when we evaluate <code>my-list</code> it will return the list as a result</p> <p>However, if we create a list directly by using <code>(1 2 3 4)</code>, this will fail when evaluated as <code>1</code> is not a function.  So when we define a data structure as a list we need to use the <code>quote</code> function or ' syntax</p> <pre><code>(quote (1 2 3 4))\n'(1 2 3 4)\n</code></pre>"},{"location":"data-structures/list/#hintfirst-element-of-a-list-is-a-function-call","title":"Hint::First element of a list is a function call","text":"<p>The first element of a list is evaluated as a function call, unless the list is wrapped in a quote function</p>"},{"location":"data-structures/list/#testing-for-a-list","title":"Testing for a List","text":"<p>When is a list not a <code>list?</code>.  Lists are sometimes created as other types if they are created in ways other than using the <code>list</code> function.  If you want to know if something is list like, then you can use the <code>seq?</code> function.  If you test with the <code>list?</code> function and that returns false, you can use the <code>type</code> function to see what its real type is.</p> <p>See more about the types that list-like structures actually are in the article: What is a list? The ultimate predicate showdown</p>"},{"location":"data-structures/naming/","title":"Naming data structures","text":"<p>We have seen that defining things is as simple as giving a name to a value using the <code>def</code> function.  It is the same for the Clojure data structures and any other values.</p> <pre><code>(def people [\"Jane Doe\" \"Samuel Peeps\"])\n</code></pre> <p>Names are of course case sensitive, so Person is not the same as person</p> <pre><code>(def Person \"James Doh\" \"Sam Stare\")\n</code></pre> <p>Clojure uses dynamic typing, this means its trivial to mix and match different kinds of data.  Here we are defining a name for a vector, which contains numbers, a string and name of another def.</p> <pre><code>(def my-data [1 2 3 \"frog\" person])\n\nmy-data\n</code></pre>"},{"location":"data-structures/naming/#data-structures-are-immutable-names-are-mutable","title":"Data structures are immutable, names are mutable","text":"<p>You can dynamically re-define a name to points to a different value.</p> <p>Hint This re-definition (or rebinding) of names to new values is typically used only during the development of your code, especially in REPL driven development.</p> <pre><code>(def my-data [1 2 3 4 5 \"frog\" person])\n</code></pre> <p>The original value that defined my-data remains unchanged (its immutable), so anything using that value remains unaffected.  Essentially we are re-mapping my-data to a new value.</p> <p>Lets define a name to point to a list of numbers</p> <pre><code>(def my-list '(1 2 3))\n</code></pre> <p>We are returned that list of numbers when we evaluate the name</p> <pre><code>my-list\n</code></pre> <p>We can use the cons function to add a number to our list, however because lists are immutable, rather than changing the original list, a new one is returned.  So if we want to keep on referring to our \"changed\" list, we need to give it a name</p> <pre><code>(def my-list-updated (cons 4 my-list))\n</code></pre> <p>As you can see we have not changed the original list</p> <pre><code>my-list\n</code></pre> <p>;; The new list does have the change though.</p> <pre><code>my-list-updated\n</code></pre> <p>You could therefore give the impression of mutable state by applying a function to data structure and redefining the original name to point to the resulting data structure.</p> <p>Hint In practice, the ability to redefine functions and data structures live helps you develop your application quickly in the REPL.</p> <p>In production you typical do not redefine functions or data structures in a live running application.  That could be part of a new release of your application though.</p> <pre><code>(def my-list (cons 5 my-list))\n</code></pre> <p>So now when we evaluate the original name, we get the updated list</p> <pre><code>my-list\n</code></pre>"},{"location":"data-structures/naming/#naming-scope","title":"Naming Scope","text":"<p>All def names are publicly available via their namespace.  As def values are immutable, then keeping things private is of less concern than languages built around Object Oriented design.</p> <p>Private definitions syntax can be used to limit the access to def names to the namespace they are declared in.</p> <p>To limit the scope of a def, add the :private true metadata key value pair.</p> <pre><code>(def ^{:private true} some-var :value)\n\n(def ^:private some-var :value)\n</code></pre> <p>The second form is syntax sugar for the first one.</p> <p>You could also define a macro for def-</p> <pre><code>(defmacro def- [item value]\n  `(def ^{:private true} ~item ~value)\n)\n</code></pre> <p>You would then use this macro as follows:</p> <pre><code>(def- private-definition \"This is only accessible in the namespace\")\n</code></pre>"},{"location":"data-structures/pretty-printing/","title":"Pretty Printing data structures","text":"<p>Data structures containing small amounts of data are quite human readable, although can benefit from pretty printing to make them very easy for humans to read.</p> <p>The larger a data structure becomes, or if a data structure is nested, then there are tools to print out ascii views of the data structures.</p>"},{"location":"data-structures/pretty-printing/#pretty-print-hash-maps","title":"Pretty print hash-maps","text":"<pre><code>(clojure.pprint/pprint\n  {:account-id 232443344 :account-name \"Jenny Jetpack\" :balance 9999 :last-update \"2021-12-12\" :credit-score :aa} )\n</code></pre> <p>Each key is printed on a new line, making the hash-map easier to read, especially when there are a large number of keys</p> <pre><code>{:account-id 232443344,\n :account-name \"Jenny Jetpack\",\n :balance 9999,\n :last-update \"2021-12-12\",\n :credit-score :aa}\n</code></pre> <p>Clojure aware editors can also have an align option when formatting hash-maps, making the results easier to read</p> <pre><code>{:account-id   232443344,\n :account-name \"Jenny Jetpack\",\n :balance      9999,\n :last-update  \"2021-12-12\",\n :credit-score :aa}\n</code></pre>"},{"location":"data-structures/pretty-printing/#hintpretty-print-evaluation-results","title":"Hint::Pretty Print evaluation results","text":"<p>Clojure aware editors should allow the pretty printing of the evaluation results.</p>"},{"location":"data-structures/pretty-printing/#print-table-of-nested-data-structures","title":"Print Table of nested data structures","text":"<p>Nested data structures can also be shown as a table, especially the common approach of using a vector of hash-maps where each map has the same keys</p> <pre><code>(clojure.pprint/print-table\n  [{:location \"Scotland\" :total-cases 42826 :total-mortality 9202}\n   {:location \"Wales\" :total-cases 50876 :total-mortality 1202}\n   {:location \"England\" :total-cases 5440876 :total-mortality 200202}])\n</code></pre> <pre><code>| :location | :total-cases | :total-mortality |\n|-----------+--------------+------------------|\n|  Scotland |        42826 |             9202 |\n|     Wales |        50876 |             1202 |\n|   England |      5440876 |           200202 |\n</code></pre>"},{"location":"data-structures/pretty-printing/#references","title":"References","text":"<p>Data browsers (Cider Inspector, Portal, Reveal Free) are very useful for larger and nested data structures.</p>"},{"location":"data-structures/set/","title":"Set","text":"<p>A Clojure set is a persistent data structure that holds a unique set of elements.  Again the elements can be of any type, however each element must be unique for a valid set.</p> <p>Note Explore creating sets from existing collections.  Notice what happens if you have duplicate values in the collection.  Define sets directly using the <code>#{}</code> notation and see what happens if there are duplicate values.</p> <pre><code>(set `(1 2 3 4))\n(set `(1 2 1 2 3 4))\n\n#{1 2 3 4}\n#{:a :b :c :d}\n;; duplicate key error\n#{1 2 3 4 1}\n</code></pre>"},{"location":"data-structures/set/#unique-but-not-ordered","title":"Unique but not ordered","text":"<p>A set is not ordered by the values it contains.  If you need a sorted set then you can use the <code>sorted-set</code> function when creating a new set.  Or you can run</p> <pre><code>(sorted-set 1 4 0 2 9 3 5 3 0 2 7 6 5 5 3 8)\n\n(sort [9 8 7 6 5])\n(sort-by )\n</code></pre>"},{"location":"data-structures/set/#looking-up-values-in-a-set","title":"Looking up values in a set","text":"<pre><code>(#{:a :b :c} :c)\n(#{:a :b :c} :z)\n</code></pre> <p>Sets can also use the <code>contains?</code> function to see if a value exists in a set</p> <pre><code>(contains?\n  #{\"Palpatine\" \"Darth Vader\" \"Boba Fett\" \"Darth Tyranus\"}\n  \"Darth Vader\")\n</code></pre>"},{"location":"data-structures/shared-memory/","title":"Shared memory with Persistent data structures","text":"<p>The Clojure data structures are immutable, so they initially seem similar to constants rather than variables.  Once a collection is created, it cannot be changed.  Any functions that run on a collection do not change the collection, instead they return a new collection with the respective changes.</p> <p>Creating a new collection each time may seem inefficient, however, the persistent collections use a sharing model.  When a new collection is created, it links to all the relevant elements of the original collection and adds any new elements.</p> <p></p> <p>Hint Read the InfoQ article on An In-Depth Look at Clojure Collections.</p>"},{"location":"data-structures/vector/","title":"Vector","text":"<p>Vectors are an indexed sequential collections of data, basically the same as arrays in other languages.  However, there are several differences.  The index for a vector starts at 0, just like arrays in other languages.</p> <p></p> <p>Vectors are written using square brackets <code>[]</code> with any number of pieces of data inside them, separated by spaces.</p> <p>Note Experiment with creating vectors for your data structures</p> <pre><code>(vector 1 2 3 4)\n[1 2 3 4 5]\n[56.9 60.2 61.8 63.1 54.3 66.4 66.5 68.1 70.2 69.2 63.1 57.1]\n[]\n\n(def pi 3.1435893)\n[1 2.4 pi 11/4 5.0 6 7]\n[:cat :dog :rabbit :fish]\n[{:cat 1} \"fish\" \"potatoes\" \"oil\" (str \"who ate my\" \"fish n chips\")]\n\n;; Include other data structures in vectors, in this example a list is an element of the vector\n[1 2 3 '(4 5 6)]\n\n;; Are duplicate elements allowed ?\n[1 2 3 4 1]\n</code></pre> <p>Note What can you do with vectors? Vectors are easy to add more items to, delete items from, or pull arbitrary items out of. Here are some functions that operate on vectors.</p> <pre><code>(vector? [5 10 15])\n(= [] [])\n(= [] [1])\n\n(first [5 10 15])\n(rest [5 10 15])\n(nth [5 10 15] 1)\n(count [5 10 15])\n\n(conj [5 10] 15)\n</code></pre> <p>Hint When a function is effectively asking if a value is true or false, its referred to as a predicate function.  Its common practice in Clojure to place a <code>?</code> at the end of that functions name.</p>"},{"location":"data-structures/vector/#lookup-data-from-a-vector","title":"Lookup data from a Vector","text":"<pre><code>([1 2 3] 1)\n\n;; ([1 2 3] 1 2)  ;; wrong number of arguments, vectors behaving as a function expect one parameter\n\n;; ((1 2 3) 1) ;; you cant treat lists in the same way, there is another approach - assoc\n</code></pre>"},{"location":"data-structures/vector/#changing-vectors","title":"Changing vectors","text":"<p>The next two functions are used to make new vectors. The <code>vector</code> function takes any number of items and puts them in a new vector.</p> <p><code>conj</code> takes a vector and an item and returns a new vector with that item added to the end. The function name is taken from the verb \"conjugate\", meaning \"to join together.</p> <p>Remember that  collections in Clojure are immutable, so when we say that a function \"adds to\" or \"removes from\" a collection, what we mean is that the function returns a new collection with an item added or removed.</p> <p>Note Using one or more vectors, create a data structure of the high temperatures for the next 7 days in your area. Use the <code>nth</code> function to get the high temperature for next Friday</p>"},{"location":"data-structures/hash-maps/","title":"Data Structures: Hash-maps","text":"<p>Associative collection of key value pairs</p> <p>Useful for defining self-describing structured data (assuming meaningful key names are used)</p> <p>A map is a key / value pair data structure.  Keys are usually defined using a keyword, although they can be strings or anything else.</p> <p>Keywords point to themselves, so using them for the keys makes it very easy to get values out of the map, or for updating existing values in the map.</p> <p>Note Explore creating maps</p> <pre><code>{:key \"value\"}\n{:key :value}\n{\"key\" \"value\"}\n(\"key\" :value)\n(:meaining-of-life 42)\n{:a 1 :b 2 :c 3}\n{:monday 1 :tuesday 2 :wednesday 3 :thursday 4 :friday 5 :saturday 6 :sunday 7}\n{1 \"Monday\" 2 \"Tuesday\" 3 \"Wednesday\" 4 \"Thursday\" 5 \"Friday\" 6 \"Saturday\" 7 \"Sunday\"}\n</code></pre>"},{"location":"data-structures/hash-maps/#hintcomma-characters-are-treated-as-white-space","title":"Hint::Comma characters are treated as white-space","text":"<p>The comma character is rarely used in Clojure hash-maps as it is ignored by Clojure.  When coming from other languages, it may be initially comforting to include commas.</p>"},{"location":"data-structures/hash-maps/#nested-data-models","title":"Nested data models","text":"<p>nested maps to create a hierarchy or path for data.  This can add more context to the overall design</p> <p>various types of data</p>"},{"location":"data-structures/hash-maps/#hintone-data-structure-to-rule-them-all","title":"Hint::One data structure to rule them all","text":"<p>It is preferred to have a single data structure to model the data of a system, which is them used by all the functions of that system.  An example is in the state used for an application, e.g. Practicalli website practicalli.data namespace</p> <p>If there is no logical connection between data across a system, then data should be grouped into one structure per namespace as a minimal approach.</p>"},{"location":"data-structures/hash-maps/#example-use-data-sets","title":"Example use: Data sets","text":"<p>A collection of maps which have the same form, e.g. a vector of hash-maps with the same keys</p> <p>Example: meteorological recordings</p> <pre><code>(def recording-station-876WA\n [{:timestamp \"2021-12-01T12:00\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.4 :rainfail 0.1 :uv-level 0.4}\n  {:timestamp \"2021-12-01T12:10\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.6 :rainfail 0.1 :uv-level 0.45}\n  {:timestamp \"2021-12-01T12:00\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.9 :rainfail 0.1 :uv-level 0.5}])\n</code></pre> <p>Providing a collection of consistent hash-map data structures is very easy to work with in Clojure.</p> <p><code>reduce</code>, <code>filter</code> and <code>map</code> functions can easily process this form of data as part of algorithms to interpret the meaning from a data set.</p> <p>As each recording station creates the same types of data, then they can be merged by including the recording station id in the map</p>"},{"location":"data-structures/hash-maps/access/","title":"Accessing hash-maps","text":"<p>The values in a hash-map can be accessed in multiple ways</p> <ul> <li><code>get</code></li> <li><code>get-in</code></li> <li><code>contains?</code></li> <li>using hash-map as a function</li> <li>use :keyword as a function</li> <li>threading hash-map through one or more keys</li> </ul> <p>Clojure provides a get function that returns the value mapped to a key in a set or map.</p>"},{"location":"data-structures/hash-maps/access/#get-and-get-in-functions","title":"get and get-in functions","text":"<p><code>get</code> is a very explicitly named function that makes its purpose very clear.  The <code>get</code> function works regardless of the type of keys used in the hash-map.</p> <p><code>(get map key)</code></p> <p><code>get-in</code> has the same quality, for use with nested hash-maps.</p> <pre><code>(get-in nested-map [:keys :path])\n</code></pre> <pre><code>(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [\"scores\" \"FSU\"])\n;;=&gt; 31\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [\"scores\"])\n;;=&gt; {\"FSU\" 31, \"UF\" 7}\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [])\n;;=&gt; {\"timestamp\" 1291578985220, \"scores\" {\"FSU\" 31, \"UF\" 7}}\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} nil)\n;;=&gt; {\"timestamp\" 1291578985220, \"scores\" {\"FSU\" 31, \"UF\" 7}}\n</code></pre>"},{"location":"data-structures/hash-maps/access/#hintmissing-or-incorrect-key","title":"Hint::missing or incorrect key","text":"<p>If the key in the path is missing or the path is missing (or nil) then <code>get-in</code> will return more of the hash-map than expected.</p>"},{"location":"data-structures/hash-maps/access/#using-hash-map-as-a-function","title":"Using hash-map as a function","text":"<p>A hash-map (and list, vector, set) can be called as a function with a key as the argument.  This provides a more terse expression than using <code>get</code> and also works irrespective of key types used.</p> <p>Passing the key <code>:star-wars</code> to the hash-map returns the value associated with that key</p> <pre><code>({:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}} :star-wars)\n</code></pre> <p>A nested hash-map (containing other hash-maps) can be accessed via multiple nested calls to the returned values.</p> <pre><code>((({:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}} :star-wars) :characters) :jedi)\n</code></pre>"},{"location":"data-structures/hash-maps/access/#keyword-key-as-a-function","title":"keyword key as a function","text":"<p>A keyword can be called as a function, taking a hash-map as an argument</p> <pre><code>(:star-wars {:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}})\n</code></pre> <p>A nested hash-map (containing other hash-maps) can be accessed via multiple nested calls to the returned values.</p> <pre><code>(:jedi (:characters (:star-wars {:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}})))\n</code></pre>"},{"location":"data-structures/hash-maps/access/#threading-macro","title":"Threading macro","text":"<p>Using keyword keys as functions, the thread macros provide a consistent approach to accessing hash-map data</p> <p>The hash-map is passed through one or more keyword keys, so obtaining values from a flat or nested hash-map is just the same.</p> <pre><code>(-&gt; hash-map\n    :keyword1\n    ,,,)\n</code></pre> <p>If the keys are a type other than keywords, then a get function would be required for accessing the hash-map.</p> <pre><code>(-&gt; hash-maps (get \"scores\") (get \"FSU\"))\n</code></pre> <p>As part of a processing pipeline, taking specific values from a JSON file of association football match statistics</p> <pre><code>(-&gt; match-statistics.json\n    (clojure.data.json/read-str :key-fn keyword)\n    :totals\n    :goals-home-team)\n</code></pre>"},{"location":"data-structures/hash-maps/access/#checking-a-key-or-value-exists-in-a-hash-map","title":"Checking a key or value exists in a hash-map","text":"<p><code>keys</code> function will return a collection of the keys contained in a map.  <code>vals</code> returns a collection of the values</p> <p>is in a map or set. In general I use the value returned from a map or set to determine if a key exists - the following snippet uses that pattern.</p> <p>Check if a key has a specific value</p> <pre><code>(if (star-wars-map :space-ships)\n  (do-true-behaviours)\n  (do-false-behaviours))\n</code></pre> <p>Check a key has a specific value and also use that value</p> <p>TODO: is this a good case for if-lets</p> <p>This pattern fails if the value of :key is nil.</p>"},{"location":"data-structures/hash-maps/access/#contains-and-some","title":"contains? and some","text":"<p><code>contains?</code> checks for the index of a collection.  The index of a hash-map is the keys it contains</p> <p><code>some</code> will check for a value in a collection</p> <pre><code>(def recipe-map {:ingredients \"tofu\"})\n\n(contains? recipe-map :ingredients)\n;; =&gt; true\n\n(some #{\"tofu\"} recipe-map)\n;; =&gt; nil\n\n(vals recipe-map)\n;; =&gt; (\"tofu\")\n\n(some #{\"tofu\"} (vals recipe-map))\n;; =&gt; \"tofu\"\n</code></pre> <p>The key is contained as part of the hash-map index, irrespective of the value associated with that key (so long as there is a legal value associate with the key).</p> <pre><code>(contains? {:totals nil} :totals)\n</code></pre>"},{"location":"data-structures/hash-maps/accessing-nested-hash-maps/","title":"Accessing Nested Hash-maps","text":"<p>Its also quite common to have maps made up of other maps, maps of vectors or vectors of maps.</p> <p>Now we can refer to the characters using keywords.  Using the get function we return all the information about Luke</p> <pre><code>(get star-wars-characters :luke)\n(get (get star-wars-characters :luke) :fullname)\n</code></pre> <p>By wrapping the get function around our first, we can get a specific piece of information about Luke.  There is also the get-in function that makes the syntax a little easier to read</p> <pre><code>(get-in star-wars-characters [:luke :fullname])\n(get-in star-wars-characters [:vader :fullname])\n</code></pre> <p>Or if you want the data driven approach, just talk to the map directly</p> <pre><code>(star-wars-characters :luke)\n(:fullname (:luke star-wars-characters))\n(:skill (:luke star-wars-characters))\n\n(star-wars-characters :vader)\n(:skill (:vader star-wars-characters))\n(:fullname (:vader star-wars-characters))\n</code></pre> <p>And finally we can also use the threading macro to minimise our code further</p> <pre><code>(-&gt; star-wars-characters\n    :luke)\n\n(-&gt; star-wars-characters\n    :luke\n    :fullname)\n\n(-&gt; star-wars-characters\n    :luke\n    :skill)\n</code></pre> <p>This technique is called destructuring.  Find out more on Destructuring</p> <p>Duplicate keys in a map are not allowed, so the following maps...</p> <pre><code>{\"fish\" \"battered\" \"chips\" \"fried\" \"fish\" \"battered and fried\"}\n{:fish \"battered\" :chips \"fried\" :fish \"battered &amp; fried\"}\n\n;; ...throw duplicate key errors\n\n;; Duplicate values are okay though\n{:fish \"fried\" :chips \"fried\" :peas \"mushy\"}\n</code></pre>"},{"location":"data-structures/hash-maps/create/","title":"Creating Hash-maps","text":"<p>Hash-maps can be defined literally using <code>{}</code> and including zero or more key / value pairs.  Keys and values can be any legal Clojure type.</p> <p>Keywords are very commonly used for keys as they provide a convenient way to look up values.</p>"},{"location":"data-structures/hash-maps/create/#literal-hash-map-examples","title":"Literal hash-map examples","text":"<p>A hash-map defining Obi-wan, a character from the Star Wars universe.</p> <pre><code>{:name \"Obi-wan Kenobi\" :homeworld \"Stewjon\"}\n</code></pre> <p>A hash-map defining Leia, another character from the Star Wars with additional information</p> <pre><code>{:name \"Leia Skywalker\" :homeworld \"Alderaan\" :birthplace \"Polis Massa\"}\n</code></pre> <p>Use <code>def</code> to bind a name to a hash-map, making it easier to pass the map to a function as an argument.</p> <pre><code>(def luke {:name \"Luke Skywalker\" :homeworld \"Tatooine\" :birthplace \"Polis Massa\"})\n</code></pre>"},{"location":"data-structures/hash-maps/create/#data-set-of-maps","title":"Data set of maps","text":"<p>Create a data set by defining a vector of hash-maps</p> <pre><code>[{:name \"Obi-wan Kenobi\"  :homeworld \"Stewjon\"   :occupation \"Jedi\"}\n {:name \"Jyn Erso\"        :homeworld \"Vallt\"     :occupation \"Soldier\"}\n {:name \"Leia Skywalker\"  :homeworld \"Alderaan\"  :occupation \"Senator\"}\n {:name \"Luke Skywalker\"  :homeworld \"Tatooine\"  :occupation \"Jedi\"}\n {:name \"Qui-Gon Jinn\"    :homeworld \"Coruscant\" :occupation \"Jedi\"}\n {:name \"Padm\u00e9 Amidala\"   :homeworld \"Naboo\"     :occupation \"Senator\"}\n {:name \"Sheev Palpatine\" :homeworld \"Naboo\"     :occupation \"Supreme Chancellor\"}]\n</code></pre>"},{"location":"data-structures/hash-maps/create/#example-nested-hash-maps","title":"Example: nested hash-maps","text":"<p>Create a map to represent the world of Star Wars, including various characters &amp; ships, indicating the factions that characters and ships belong to.</p> <p>Individual Star Wars characters can be defined using a map of maps</p> <pre><code> {:luke   {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n  :vader  {:name \"Darth Vader\"    :skill \"Breaking the rules and peoples hearts\"}\n  :jarjar {:name \"JarJar Binks\"   :skill \"Failing upwards\"}}\n</code></pre> <p>Hash-maps can also use other collections as values</p> <pre><code>{:characters\n  {:jedi   [\"Luke Skywalker\" \"Obiwan Kenobi\"]\n   :sith   [\"Darth Vader\" \"Darth Sideous\"]\n   :droids [\"C3P0\" \"R2D2\" \"BB8\"]}\n :ships\n   {:rebel-alliance  [\"Millennium Falcon\" \"X-wing fighter\"]\n    :imperial-empire [\"Intergalactic Cruiser\" \"Destroyer\"\n                      \"Im just making these up now\"]}}\n</code></pre> <p>Use the def function to bind a name to the Star Wars character information, making it easier to pass to several functions</p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Breaking the rules and peoples hearts\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Failing upwards\"}})\n</code></pre>"},{"location":"data-structures/hash-maps/create/#generating-hash-maps","title":"Generating hash-maps","text":"<p><code>hash-map</code> is a clojure.core function that returns a hash-map of the given arguments, or an empty hash-map, <code>{}</code>, if no arguments are given.</p> <p>Arguments should be key-value pairs, otherwise the function will return nil</p>"},{"location":"data-structures/hash-maps/create/#converting-collections-to-hash-maps","title":"Converting collections to hash-maps","text":"<pre><code>(apply hash-map [:a 1 :b 2])\n;;=&gt; {:b 2 :a 1}\n</code></pre> <p>Order of keys in a hash-map is not guaranteed.  However, order of keys should be irrelevant as the keys are unique within a map.</p> <pre><code>(into {} ,,,)\n</code></pre> <p>map</p> <p>reduce</p> <p>merge returns a hash-map that is a merging of the key value pairs from all maps, for any duplicate keys the value from the last key (left to right) is used</p>"},{"location":"data-structures/hash-maps/create/#setting-default-values","title":"Setting default values","text":"<p>Calling a function with a hash-map as an argument is a flexible way to design the API of a namespace and Clojure application in general.</p> <p>As functions are talking a map, a function call with fewer or more keys than needed will still result in a successful call (alhtough results could be interesting)</p> <p>If fewer keys are passed then defaults can be set.</p> <p><code>merge</code> can be used to ensure any required keys with default values are always present, and still over-ridden by keys passed in as an argument</p> <p><code>merge</code> should passed the default key values first, with the argument map merged on top. This ensures all keys are present and that the argument values are used if duplicate keys exist between the maps.</p> <pre><code>(merge {:option1 \"default-value\" :option2 \"default-value\"}\n       {:option1 \"custom-value\"})\n;;=&gt; {:option1 \"custom-value\" :option2 \"default-value\"}\n</code></pre> <p>The <code>merge</code> function can be used in a function to return the merged map of default and argument values When a function has a number of options  with default values.</p> <pre><code>(defn parse-cli-tool-options\n  \"Return the merged default options with any provided as a hash-map argument\"\n[arguments]\n   (merge {:replace false :report true :paths [\".\"]}\n          arguments))\n\n(parse-cli-tool-options {:paths [\"src\" \"test\"] :report false})\n;; =&gt; {:replace false, :report false, :paths [\"src\" \"test\"]}\n</code></pre> <p>If an empty hash-map is sent as an argument, the default values are returned</p> <pre><code>(parse-cli-tool-options {})\n;; =&gt; {:replace false, :report true, :paths [\".\"]}\n</code></pre> <p>zipmap</p> <pre><code>(zipmap [:a :b :c] [1 2 3])\n;; =&gt; {:a 1, :b 2, :c 3}\n</code></pre>"},{"location":"data-structures/hash-maps/create/#custom-merging-with-a-function","title":"Custom merging with a function","text":""},{"location":"data-structures/hash-maps/create/#create-a-sub-set-of-existing-map","title":"Create a sub-set of existing map","text":""},{"location":"data-structures/hash-maps/create/#filter","title":"filter","text":"<p>Create a sub-set of an existing map</p> <p>;; #61 - Map Construction ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Difficulty: Easy ;; Topics: core-functions ;; Special Restrictions: zipmap</p> <p>;; Write a function which takes a vector of keys and a vector of values and constructs a map from them.</p> <p>;; Tests (= ([:a :b :c] [1 2 3]) {:a 1, :b 2, :c 3}) (= ( [1 2 3 4] [\"one\" \"two\" \"three\"]) {1 \"one\", 2 \"two\", 3 \"three\"}) (= (__ [:foo :bar] [\"foo\" \"bar\" \"baz\"]) {:foo \"foo\", :bar \"bar\"})</p> <p>;; If we could use zipmap then the answer would be simple</p> <p>(zipmap [:a :b :c] [1 2 3]) ;; =&gt; {:a 1, :b 2, :c 3}</p> <p>(= (zipmap [:a :b :c] [1 2 3]) {:a 1, :b 2, :c 3}) ;; =&gt; true</p> <p>;; So now we have to figure out the algorithm that zipmap uses</p> <p>;; Analyse the problem ;; We want to create a paring of values from the first and second vectors ;; Then each pair should be made into a key value pair within a map data structure.</p> <p>;; The map function will work over multiple collections, returning a single collection</p> <p>;; A simple example of map function in action: (map str [:a :b :c] [1 2 3]) ;; =&gt; (\":a1\" \":b2\" \":c3\")</p> <p>;; In stead of string, we could use hash-map</p> <p>(map hash-map [:a :b :c] [1 2 3]) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>;; now we just need to put all the maps into one map, so perhaps merge will work</p> <p>(merge (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>(conj (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>(reduce conj (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; {:c 3, :b 2, :a 1}</p> <p>;; (reduce conj (map vectork ks vs))</p> <p>((fn [key-sequence value-sequence]    (into {}          (map vector key-sequence value-sequence)))  [:a :b :c] [1 2 3]) ;; =&gt; {:a 1, :b 2, :c 3}</p>"},{"location":"data-structures/hash-maps/update/","title":"Update Hash-maps","text":""},{"location":"defining-behaviour-with-functions/","title":"Defining behaviours with functions","text":"<p>Clojure has functions, rather than methods for defining behaviour / \"algorithms\"</p> <p>Clojure design at its most basic comprises:</p> <ul> <li>one or more data structures</li> <li>functions that process those data-structures</li> </ul> <p>There is a common saying in Clojure: \"Its better to have one data structure and many functions, than many data structures and many functions\"</p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/","title":"Anonymous Functions","text":"<p><code>clojure.core/fn</code> is a function for defining custom functions.</p> <p><code>fn</code> is called the anonymous function as it has no external name by which it can be referred by. They are used within the scope of another function call, as having no name they cannot be called from another part of the code.</p> <pre><code>(map (fn [args] ,,,) [1 2 3])\n((fn [args] ,,,))\n</code></pre> <p>The value of using anonymous functions comes when there is a short, specific piece of behaviour required which is unlikely to be needed elsewhere in the code.  An anonymous function can always be refactored into a <code>defn</code> expression if used in multiple places.</p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#definition-of-an-anonymous-function","title":"Definition of an anonymous function","text":"<pre><code>(fn [argument] (str \"some behaviour, typically using the arguments passed:\" argument ))\n</code></pre> <p>This expression is a function call to <code>fn</code> which has the arguments called <code>argument</code></p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#calling-an-anonymous-function","title":"Calling an anonymous function","text":"<p>To get a value from evaluating this function you need to pass it a value (or another function) as an argument,  as well as calling it as a function by placing the anonymous function as the first element of a list.</p> <pre><code>((fn [arguments] (str \"behaviour, typically using the arguments passed: \" arguments )) \"Is this the right room for an argument\")\n</code></pre>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#binding-a-local-names","title":"Binding a local names","text":"<p><code>fn</code> can have a local name which can be used to write a recursive function (a fn that calls itself).</p> <p>Adding a name also helps with debugging code, as the name will be used to identify that function call if it appears in a stack trace of an exception.</p> <p>A recursive function that counts the elements in a collection</p> <pre><code>(fn -count [xs]\n  (if (empty? xs)\n    0\n    (inc (-count (rest xs)))))\n</code></pre> <pre><code>(fn meaningful-name\n  []\n  (str \"If I fail, you will know my name\"))\n</code></pre>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#anonymous-function-syntactic-sugar","title":"Anonymous function Syntactic Sugar","text":"<p>There is a short form of the function definition using the <code>#( ,,, )</code> syntax.</p> <p>For example, if we want to increment an argument we could start to define an anonymous function as follows:</p> <pre><code>#(inc %)\n</code></pre> <p>The <code>%</code> represents a placeholder for an argument that is passed into the anonymous function.  This argument is anonymous as well as the value is simply swapped into the position of <code>%</code>.</p> <p>To evaluate this anonymous function we need to give it an argument to work on.  Anything after the anonymous function is taken as its argument.  So in the following expression we pass the value 1 as the argument and we should get the result of incrementing 1 as a result</p> <pre><code>( #(inc %) 1 )\n\n;; =&gt; 2\n</code></pre> <p>The <code>%</code> placeholder can also refer to a specific argument by adding an index number.  The index numbers refer to the position of the arguments supplied to the anonymous function.</p> <p>Here we will add two different arguments together</p> <pre><code>( #(+ %1 %2) 20 22)\n</code></pre> <p>So <code>%1</code> will represent the first argument and the <code>%2</code> will represent the second argument passed to this function.</p> <p>Sometimes position can be important as the following two versions of code demonstrate</p> <pre><code>( #(/ %1 %2) 24 6)\n\n( #(/ %2 %1) 24 6)\n</code></pre> <p>These two expressions give different values (and return different types, Integer and Ratio) as the positions of the arguments have been reversed.</p>"},{"location":"defining-behaviour-with-functions/calling-functions/","title":"Calling Functions","text":"<p>To call a function in Clojure you use the name of the function as the first element of a list.</p> <p>In this simple example, a function is defined that takes no arguments, then that function is called.</p> <pre><code>(defn my-function []\n  (str \"I only return this string\"))\n\n(my-function)\n</code></pre> <p>Functions can be defined to take arguments.</p>"},{"location":"defining-behaviour-with-functions/calling-functions/#arity","title":"Arity","text":"<p>This is the term to describe the number of arguments a function takes.  This can be a fixed number or variable number of arguments.</p> <p>Simple polymorphism can also be used to have one function take different numbers of arguments, as with the <code>multi-arity</code> function in the examples below.</p> <pre><code>(defn single-arity [] \n  (str \"I do not take any arguments\"))\n\n(defn single-arity [argument] \n  (str \"I take 1 argument only\"))\n\n(defn triple-arity [argument1 argument2 argument3] \n  (str \"I take 3 arguments only\"))\n\n(defn multi-arity \n ([argument] \n   (str \"I match 1 argument only\"))\n ([argument1 argument2]\n   (str \"I match when 2 arguments are used\")))\n\n(defn variable-arity [argument &amp; more-arguments]\n  (str \"I assign the first argument to argument, \n        all other arguments to more-arguments\"))\n</code></pre>"},{"location":"defining-behaviour-with-functions/examples/","title":"Examples","text":""},{"location":"defining-behaviour-with-functions/parameters/","title":"Parameters","text":""},{"location":"defining-behaviour-with-functions/syntax/","title":"Syntax","text":"<p>Defining functions is done with the <code>fn</code> function</p> <p>We have already seen the <code>def</code> function to assign names to values.  We can also use the same function to give a name to our functions.</p>"},{"location":"designing-data-structures/","title":"Designing Data Structures","text":"<p>Some common design guides for data structures in Clojure</p>"},{"location":"designing-data-structures/#the-basics-design-approach","title":"The Basics design approach","text":"<p>Most data structures in Clojure seem to be created from either vectors or maps or a combination of both.  Sets are used where uniqueness of values is important and lists are often used for their lazy properties.</p> <p>Vectors are the most flexible data structure in Clojure and support none-sequential access as they are indexed.</p> <p>Maps are really useful for defining semantic meaning to your data structures, helping you create data structures that express the context of the model they represent.  Maps give you unordered, arbitrary index arrangement. Access is iteration of key/value pairs or getting a value for a given key.</p> <p>Lists give you sequential, one-at-a-time arrangement. They allow for efficient iteration, lazy generation, and stack discipline.</p> <p>Sets give you unordered, unique constraint arrangement. Access is iteration of elements or checking containment.</p>"},{"location":"designing-data-structures/modeling-alphabet-codes/","title":"Model alphabet codes","text":"<p>Maps in Clojure are used to model key and value pairs.</p> <ul> <li>Keys must be unique within a map.</li> <li>A key can be a number, string or keyword.</li> </ul> <p>Vectors in Clojure are a general data structure that are good for handing any kind of information.</p> <p>Note Define a data structure where each letter of the alphabet is represented by a 6 digit binary code</p> <p>Lets define a name called <code>alphabet</code> that is bound to a map.  Each key in the map is a character of the alphabet and each value is a vector of numbers that represent a binary code.</p> <p>The map also includes a binary code for a full stop and space character</p> <pre><code>(def alphabet {\"A\" [0 1 0 0 0 1]\n               \"B\" [0 0 1 0 1 0]\n               \"C\" [0 1 0 0 1 0]\n               \"D\" [1 0 1 0 0 0]\n               \"E\" [1 0 1 1 0 0]\n               \"F\" [1 1 0 1 0 0]\n               \"G\" [1 0 0 1 1 0]\n               \"H\" [1 0 1 0 0 1]\n               \"I\" [1 1 1 0 0 0]\n               \"J\" [0 0 1 1 1 1]\n               \"K\" [0 1 0 1 0 1]\n               \"L\" [1 1 1 0 0 1]\n               \"M\" [1 1 1 0 1 1]\n               \"N\" [0 1 1 1 0 1]\n               \"O\" [1 1 0 1 1 0]\n               \"P\" [1 1 1 1 1 0]\n               \"Q\" [1 0 1 1 1 0]\n               \"R\" [1 1 1 1 0 0]\n               \"S\" [0 1 1 1 1 0]\n               \"T\" [1 0 0 1 1 1]\n               \"U\" [0 0 1 0 1 1]\n               \"V\" [0 1 1 0 0 1]\n               \"W\" [1 1 0 1 0 1]\n               \"X\" [1 0 1 0 1 0]\n               \"Y\" [1 0 0 0 1 1]\n               \"Z\" [1 1 0 0 1 1]\n               \".\" [1 0 1 1 0 1]\n               \" \" [0 0 1 0 0 0]})\n</code></pre>"},{"location":"designing-data-structures/modeling-name-generation-map/","title":"Design a map for name generation","text":"<p>Imagine you are writing a simple name generator that takes your name and creates an alternative version.  For example this could be a generator of your \"Posh\" or \"Hipster\" name.</p> <p>Note Define a data structure to model sloane names that has three names for every letter of the alphabet.  For name suggestions, see the Tattler sloane name generator.</p> <p>The following seems to be the simplest way to model the sloane names.  This follows the representation in the original source material.</p> <pre><code>(def sloane-first-name\n  {\"a\" \"Ally-Pally\"\n   \"b\" \"Bongo\"\n   \"c\" \"Chipper\"})\n\n(def slone-second-name\n  {\"a\" \"Anstruther\"\n   \"b\" \"Beaufort\"\n   \"c\" \"Cholmondeley\"})\n\n(def slone-third-name\n  {\"a\" \"Arbuthnot\"\n   \"b\" \"Battenburg\"\n   \"c\" \"Coutts\"})\n</code></pre> <p>The following alternative data structure design is very simple and more concise, however it does loose some of the semantic meaning.  The position of the names is not defined in terms of the context of the problem.</p> <pre><code>(def slone-names\n  {:a [\"Ally-Pally\" \"Anstruther\" \"Arbuthnot\"]})\n</code></pre> <p>This next design removes some of the redundancy in defining each letter of the alphabet several times.  Apart from less typing and therefore reading by the development team, it also explicitly defines the semantic meaning of each name within the context of this problem.</p> <pre><code>(def slone-names\n  {:a {:first \"Ally-Pally\" :second \"Anstruther\" :third \"Arbuthnot\"}})\n</code></pre> <p>For extra points you could try and implement a function that generated your sloane name.</p>"},{"location":"designing-data-structures/modeling-name-generation-map/#creating-the-algorithm-to-construct-your-sloane-name","title":"Creating the algorithm to construct your sloane name","text":"<ul> <li>The first sloane name is chosen from the first character of the first name</li> <li>The second sloane name chosen from the first character of the second name</li> <li>The third sloane name is chosen from the second character of the second name</li> </ul> <p>You can get the first element of a string by treating it just like a collection.  However this returns a character</p> <pre><code>(first \"Strings also act as collections\")\n</code></pre> <p>A string can be converted to a keyword, a character cannot</p> <pre><code>(keyword \"a\")\n</code></pre> <p>A character can be converted to a string using the str function</p> <pre><code>(str (first \"Strings also act as collections\"))\n</code></pre> <p>The keywords need to be the same case, so convert the first character to lower case (which returns a string, so the explicit str function is no longer required.)</p> <pre><code>(clojure.string/lower-case (first \"Strings also act as collections\"))\n</code></pre> <p>Putting it all together.</p> <pre><code>(keyword (clojure.string/lower-case (first \"Strings also act as collections\")))\n</code></pre>"},{"location":"designing-data-structures/modeling-name-generation-map/#create-a-function-to-calculate-your-sloane-name","title":"Create a function to calculate your sloane name","text":"<p>Putting all this together in a function to generate your sloan name, given your a string with your first and last name.</p> <pre><code>(defn sloane-name\n  \"Given a first and last name as a string, returns your equivalent Sloane name as a string\"\n  [name]\n  (let [first-name  (keyword (clojure.string/lower-case (first (first (clojure.string/split name #\" \")))))\n        middle-name (keyword (clojure.string/lower-case (first (second (clojure.string/split name #\" \")))))\n        last-name   (keyword (clojure.string/lower-case (second (second (clojure.string/split name #\" \")))))]\n    (str (get-in slone-names [first-name  :first])\n         \" \"\n         (get-in slone-names [middle-name :second])\n         \" \"\n         (get-in slone-names [last-name   :third]))))\n</code></pre> <p>Supply a name that will test if the <code>sloane-name</code> function works</p> <pre><code>(sloane-name \"Billy Abstainer\")\n;; =&gt; \"Bongo Anstruther Battenburg\"\n</code></pre>"},{"location":"designing-data-structures/with-maps-of-maps/","title":"With Maps of Maps","text":"<p>Note Define a collection of star-wars characters using a map of maps.  Each character should have an name that they are typically referred to, along with their fullname and skill</p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Crank phone calls\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"}})\n</code></pre> <p>Now we can refer to the characters using keywords.  Using the get function we return all the information about Luke</p> <pre><code>(get star-wars-characters :luke)\n</code></pre> <p>By wrapping the get function around our first, we can get a specific piece of information about Luke</p> <pre><code>(get (get star-wars-characters :luke) :fullname)\n</code></pre> <p>There is also the get-in function that makes the syntax a little easier to read</p> <pre><code>(get-in star-wars-characters [:luke :fullname])\n(get-in star-wars-characters [:vader :fullname])\n</code></pre> <p>Or you can get really concise by just talking to the map directly</p> <pre><code>(star-wars-characters :luke)\n(:fullname (:luke star-wars-characters))\n(:skill (:luke star-wars-characters))\n\n(star-wars-characters :vader)\n(:skill (:vader star-wars-characters))\n(:fullname (:vader star-wars-characters))\n</code></pre> <p>And finally we can also use the threading macro to minimise our code further</p> <pre><code>(-&gt; star-wars-characters\n    :luke)\n\n(-&gt; star-wars-characters\n    :luke\n    :fullname)\n\n(-&gt; star-wars-characters\n    :luke\n    :skill)\n</code></pre> <p>Note* Create a slightly  data structure holding data around several developer events.  Each event should have a website address, event type, number of attendees, call for papers.</p> <pre><code>(def dev-event-details\n  {:devoxxuk     {:URL                 \"http://jaxlondon.co.uk\"\n                  :event-type          \"Conference\"\n                  :number-of-attendees 700\n                  :call-for-papers     \"open\"}\n   :hackthetower {:URL                 \"http://hackthetower.co.uk\"\n                  :event-type          \"hackday\"\n                  :number-of-attendees 99\n                  :call-for-papers     \"closed\"}})\n</code></pre> <p>This data structure is just a map, with each key being the unique name of the developer event.</p> <p>The details of each event (the value to go with the event name key) is itself a map as there are several pieces of data associated with each event name. So we have a map where each value is itself a map.</p> <p>Call the data structure and see what it evaluates too, it should not be a surprise</p> <pre><code>dev-event-details\n</code></pre> <p>We can ask for the value of a specific key, and just that value is returned</p> <pre><code>(dev-event-details :devoxxuk)\n</code></pre> <p>In our example, the value returned from the :devoxxuk key is also a map, so we can ask for a specific part of that map value by again using its key</p> <pre><code>(:URL (dev-event-details :devoxxuk))\n</code></pre>"},{"location":"designing-data-structures/with-maps/","title":"With Maps","text":"<p>Maps allow you to model data with its contextual meaning.  The keys of a map can give the context and the values are the specific data.</p> <p>Note Define a shopping list of items you want, including how many of each item you want to buy</p> <pre><code>(def shopping-list\n  {\"cat food\"  10\n   \"soya milk\" 4\n   \"bread\"     1\n   \"cheese\"    2})\n</code></pre> <p>Note Define a star-wars characters, eg. luke skywalker, jarjar binks.  The star-wars character should include a name and a skill (it doesn't matter what these are).</p> <p>Use the 'get' function to return the value of a given key, eg. name.  Use keywords to return a given value if you used keywords for the map keys.</p> <p>In this answer we have defined three different star-wars characters, all using the same map keys.</p> <pre><code>(def luke   {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"})\n(def darth  {:name \"Darth Vader\"    :skill \"Crank phone calls\"})\n(def jarjar {:name \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"})\n</code></pre> <p>Lets see what the specific skill luke has</p> <pre><code>(get luke :skill)\n</code></pre> <p>When you use a keyword, eg. :name, as the key in a map, then that keyword can be used as a function call on the map to return its associated value.  Maps can also act as functions too.</p> <pre><code>(:name luke)\n(luke :name)\n</code></pre> <p>There are also specific functions that work on maps that give all the <code>keys</code> of a map and all the <code>values</code> of that map</p> <pre><code>(keys luke)\n(vals luke)\n</code></pre>"},{"location":"designing-data-structures/with-vectors-of-maps/","title":"A Vector of Maps","text":"<p>Vectors are good for holding any information whether that be simple values or other collections.</p> <p>Maps are good for defining data with semantic meaning, using the keys to express the context of the values.</p> <p>*Note Define a simple data structure for a collection of stocks in a portfolio.  This would contain a collection of stock information, with each stock holding the ticker name, last trading monetary value and opening monetary value.</p> <p>This is a vector of maps, as there will be one or more company stocks to track.  Each map represents the stock information for a company.</p> <pre><code>(def portfolio [ { :ticker \"CRM\"  :lastTrade 233.12 :open 230.66}\n                 { :ticker \"AAPL\" :lastTrade 203.25 :open 204.50}\n                 { :ticker \"MSFT\" :lastTrade 29.12  :open 29.08 }\n                 { :ticker \"ORCL\" :lastTrade 21.90  :open 21.83 }])\n</code></pre> <p>We can get the value of the whole data structure by referring to it by name</p> <pre><code>portfolio\n</code></pre> <p>As the data structure is a vector (ie. array like) then we can ask for a specific element by its position in the array using the <code>nth</code> function</p> <p>Lets get the map that is the first element (again as a vector has array-like properties, the first element is referenced by zero)</p> <pre><code>(nth portfolio 0)\n</code></pre> <p>The vector has 4 elements, so we can access the last element by referencing the vector using 3</p> <pre><code>(nth portfolio 3)\n</code></pre> <p>As portfolio is a collection, also known as a sequence, then we can use a number of functions that provide common ways of getting data from a data structure</p> <pre><code>(first portfolio)\n(rest portfolio)\n(last portfolio)\n</code></pre> <p>We can get specific information about the share in our portfolio, or as the keys in each map are defined with Clojure keywords, we can also use the keywords to return the specific values they pair with.</p> <pre><code>(get (second portfolio) :ticker)\n;; =&gt; \"AAPL\"\n\n(:ticker (first portfolio))\n;; =&gt; \"CRM\"\n</code></pre> <p>If we want to get specific share information across the whole portfolio, then we can simply <code>map</code> the <code>:ticker</code> keyword over each share in portfolio</p> <pre><code>(map :ticker portfolio)\n;; =&gt; (\"CRM\" \"AAPL\" \"MSFT\" \"ORCL\")\n\n(mapv :ticker portfolio)\n;; =&gt; [\"CRM\" \"AAPL\" \"MSFT\" \"ORCL\"]\n</code></pre>"},{"location":"designing-data-structures/with-vectors-of-vectors/","title":"With Vectors of Vectors","text":"<p>The most frequent use of  you will see is in the <code>project.clj</code> file, where a vector of vectors is used to model the library dependencies for a project</p> <pre><code>[[org.clojure/clojure \"1.8.0\"]\n [org.clojure/core.match \"0.3.0-alpha4\"]]\n\n[[org.clojure/clojure \"1.6.0\"]\n [ring \"1.4.0-beta2\"]\n [compojure \"1.3.4\"]\n [hiccup \"1.0.5\"]]\n</code></pre> <p>Fixme Think of an exercise to create a vector of vectors as a data model</p>"},{"location":"designing-data-structures/with-vectors/","title":"With Vectors","text":"<p>Vectors as the simplest data structure in Clojure to work with.  They are very similar to an array in other languages, although they have additional qualities in Clojure.</p> <p>Vectors</p> <ul> <li>can be of any length</li> <li>are indexed so have fast random access</li> <li>can contain any types</li> <li>are immutable</li> </ul> <p>Define a data structure for a simple shopping list with any items you would typically want to buy.</p> <pre><code>(def shopping-list [\"Cerial\" \"Baked Beans\" \"Cat food\" \"Quorn chicken pieces\" ])\n</code></pre>"},{"location":"development-environments/","title":"Development Environments","text":"<p>This workshop encourages LightTable &amp; Leiningen as the development environment, as they are the easiest tools to set up.</p> <p>Leiningen is the build automation tool used to manage Clojure projects.  It will create projects from templates and run our Clojure environment (REPL).</p> <p>LightTable is a Clojure aware editor that supports the dynamic workflow of Clojure development in a REPL.  LightTable is also written in Clojure (and ClojureScript).</p> <p>The following pages will show you how to set up LightTable and Leiningen.</p>"},{"location":"development-environments/java/","title":"Java","text":""},{"location":"development-environments/java/#java-a-host-platform-for-clojure","title":"Java - a host platform for Clojure","text":"<p>You will need to have a Java Runtime Edition (usually installed on most computers by default) to run any Clojure applications.  Version 8 is recommended (although version 6 &amp; 7 should work).</p> <p>To test if you have Java on your computer, open a command line window and run the command</p> <pre><code>java -version\n</code></pre>"},{"location":"development-environments/java/#installing-the-java-runtime-edition","title":"Installing the Java Runtime Edition","text":"<p>Download and install the latest Oracle Java SDK (version 1.8 at time of writing).</p> <p>Alternatively, install OpenJDK or Zulu build of OpenJDK</p>"},{"location":"development-environments/java/#ubuntu","title":"Ubuntu","text":"<p>The OpenJDK is available as a package on Ubuntu and can be installed via the Ubuntu software center or via the command line:</p> <pre><code>sudo apt-get install openjdk-8-jre\n</code></pre>"},{"location":"development-environments/java/#why-is-java-required","title":"Why is Java Required","text":"<p>Clojure was designed as a hosted language, which means it is developed and run on top of Java's Virtual Machine (JVM).  However, its not necessary to learn the Java language to use Clojure.</p> <p>Clojure is compiled into Java bytecode when you evaluate the code.  This compilation happens in the background so you dont usually see it happening.  For example, if you are using the Clojure REPL then each time you evaluate an expression it is compiled into Java bytecode and then injected into the running REPL and the results are then returned.  This all happens pretty instantaneously.</p> <p>Most of the current Clojure tooling was developed for Clojure on the JVM, for example Leiningen.</p> <p>As Clojure runs on Java you can also use all the other libraries that run on the Java Virtual machine, regardless of whether those libraries were written in Java, Clojure, Scala, JRuby, jython, Groovy, etc.</p>"},{"location":"development-environments/leiningen/","title":"Leiningen Build tool","text":"<p>leiningen.org (pronounced line-ing-en) is a very powerful build automation tool for automating Clojure projects.  With Leiningen you can:</p> <ul> <li>Create Clojure Projects with templates</li> <li>Define and manage dependencies</li> <li>Run an interactive Clojure environment (REPL)</li> <li>Run unit tests using Clojure.test</li> <li>Run your Clojure application</li> <li>Create a deployable Clojure application, as Java Jar file</li> <li>Deploy a Clojure library to a remote repository</li> </ul> <p></p>"},{"location":"development-environments/leiningen/#install-leiningen","title":"Install Leiningen","text":"<p>Download the install script from leiningen.org and run the Leiningen script in a terminal</p> <p>On Linux and MacOSX, make the script executable first</p> <pre><code>chmod a+x lein\n./lein\n</code></pre> <p>Hint I put the <code>lein</code> script in <code>~/bin</code> directory which is part of my operating system execution path ($PATH).  To include the <code>~/bin</code> directory in the system path, I add the following code to the <code>~/.profile</code> file</p>"},{"location":"development-environments/leiningen/#testing-leiningen-is-working","title":"Testing Leiningen is working","text":"<p>Test that Leiningen is installed with the following command</p> <pre><code>lein version\n</code></pre> <p>Output should look similar to:</p> <pre><code>Leiningen 2.6.1 on Java 9-internal OpenJDK 64-Bit Server VM\n</code></pre>"},{"location":"development-environments/lighttable/","title":"LightTable","text":"<p>LightTable is a simple development tool that supports Clojure, ClojureScript, JavaScript and Python languages.  The tool is open source and written in Clojure &amp; ClojureScript (with a little JavaScript &amp; CSS)</p> <p></p>"},{"location":"development-environments/lighttable/#install-lighttable","title":"Install Lighttable","text":"<p>Download lighttable.com and follow the suggested instructions:</p> <p>MacOSX   Install the <code>lighttable.dmg</code> file just as any other MacOSX package</p> <p>Linux   Extract the contents of the downloaded lighttable file to a suitable directory (<code>/usr/local</code> or <code>~/apps</code>).  Add <code>LightTable</code> to the system <code>$PATH</code>, or add the following script to the system <code>$PATH</code>.</p> <p>Windows   Download the windows zip file for LightTable and extract the installer, following the instructions inside the installer.</p>"},{"location":"development-environments/lighttable/#lighttable-configuration","title":"LightTable configuration","text":"<p>Lighttable configuration is in the file <code>user.behaviours</code>.  Open the user behaviours file, <code>Ctrl-space</code> and type <code>user behaviors</code>.  When you save the file, <code>Ctrl-s</code>, changes are applied immediately.</p> <p>Sample User Behaviours file</p> <p>Here is a sample of user behaviours file for LightTable</p>"},{"location":"development-environments/lighttable/#using-lighttable","title":"Using LightTable","text":"<p>LightTable has an online tutorial entitled Getting started with LightTable</p> <p>I create a project first with Leiningen, open the project directory in the LightTable workspace and open any files I want to work with.  I then connect the open editor window for the file by pressing <code>Ctrl-Enter</code> at the end of an expression.</p> <p>Hint my approach is documented in the quick demo section of my Clojure &amp; LightTable slides from JAXLondon 2013.</p>"},{"location":"development-environments/other-tools/","title":"Other Development tools for Clojure","text":"<p>There are several development tools you can use to support your Clojure development.</p> <p>My current choice of development environment is Spacemacs, a feature rich configuration for Emacs.  See my article on Spacemacs for Clojure development</p> <p>Some common setups I have seen in use for Clojure development are:</p> <ul> <li>Modern - LightTable, Leiningen, Git</li> <li>Modern Classic - Spacemacs with Clojure layer, Leiningen, magit</li> <li>Classic - Emacs with Cider, Leiningen, magit</li> <li>Java (IntelliJ) - Cursive Clojure</li> <li>Java (Eclipse) - Counterclockwise documentation site</li> <li>Ubiquitous - Vim, nailgun, Leiningen, Git</li> <li>Simple - Nightcode, Leiningen, Git</li> <li>Lightweight - Atom, Protorepl, Leiningen, Git</li> </ul> <p>There may be many more variations, however you should find a development environment with at minimum the following features:</p> <ul> <li>starting &amp; using a REPL, with in-line evaluation</li> <li>syntax highlighting &amp; coloured brackets (eg. rainbow-delimiters in Emacs)</li> <li>autocomplete of  names (functions, symbols, keywords, etc)</li> <li>snippets / templates</li> </ul>"},{"location":"development-environments/other-tools/#tools-for-developers-with-a-java-background","title":"Tools for developers with a Java background","text":"<p>Clojure runs on the Java Virtual Machine so its not surprising that there is good support for Clojure in the major Java IDEs.</p>"},{"location":"development-environments/other-tools/#eclipse","title":"Eclipse","text":"<p>Counterclockwise is an Eclipse IDE plugin to provide an integrated development environment for Clojure.  Take a look at the Counterclockwise documentation site for installation instructions</p>"},{"location":"development-environments/other-tools/#intellij","title":"IntelliJ","text":"<p>Cursive is a Clojure IDE that aims to understands your code.  Advanced structural editing, refactor, VCS integration and much more, all out of the box.  It is currently a standalone tool, although will eventually become an IntelliJ plugin.</p> <p>La Clojure is a plugin for IntelliJ IDEA.  Provides Clojure language support: syntax and error highlighting, completion, navigation and refactor.</p>"},{"location":"development-environments/other-tools/#netbeans","title":"Netbeans","text":"<p>Netbeans did have great support for Clojure, but unfortunately at the time of writing the Clojure plugin has been unmaintained for so long it is not a viable tool to use for Clojure development.</p>"},{"location":"games/","title":"Writing Games with Clojure","text":"<p>Games are driven by events and require state to be managed, so are a good way to explore how to manage state with immutable values.</p> <p>For games in Clojure the events are simply function calls and we prefer to pass the state around rather than have a central mutable container for our state.</p> <p>This section will contain several games that have been built using a functional approach with immutable data structures.</p> <ul> <li>TicTacToe on the command line</li> </ul>"},{"location":"games/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"games/#hintgames-in-clojurescript","title":"Hint::Games in ClojureScript","text":"<p>There is a section on games in the Practicalli ClojureScript book, including a TicTacToe game using Reagent (react.js style library) and Scalable Vector Graphics (SVG).</p>"},{"location":"games/tictactoe-cli/","title":"TicTacToe on the command line","text":"<p>Tic-tac-toe is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3\u00d73 grid. The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row wins the game</p> <p></p> <p> </p> <p>The code for this section is published on GitHub at: practicalli/tictactoe-cli</p> <p>A TicTacToe game that you run on the command line.  The game takes input from a human player and the program is the second player.</p> <p></p> <p>Output from the game appears in the REPL</p> <pre><code>Current board:\n1 | 2 | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | 2 | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | O\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | O\n---------\nX | 8 | 9\nPlayer  X  wins!\n</code></pre>"},{"location":"games/tictactoe-cli/#references","title":"References","text":"<ul> <li>TicTacToe game created by Brian Will.</li> </ul>"},{"location":"games/tictactoe-cli/create-project/","title":"Create a Clojure project","text":"<p>Create a project for our game.</p> <p>{% tabs deps=\"deps.edn projects\", lein=\"Leiningnen projects\" %}</p> <p>{% content \"deps\" %} Create a new project using <code>clj-new</code> alias, found in  Practicalli Clojure CLI Config</p> <pre><code>clojure -M:new practicalli/tictactoe-cli\n</code></pre> <p>Open the project in a Clojure aware editor or run a rebel REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Once the rebel REPL is running, load the project and change to the main namespace</p> <pre><code>(require 'practicalli/tictactoe-cli)\n\n(in-ns 'practicalli/tictactoe-cli)\n</code></pre> <p>{% content \"lein\" %} The default Leiningen template is suitable fine for the project as no additional libraries are used.</p> <pre><code>lein new tictactoe-cli\n</code></pre> <pre><code>git clone https://github.com/practicalli/tictactoe-cli.git\n</code></pre>"},{"location":"games/tictactoe-cli/create-project/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"games/tictactoe-cli/create-project/#hintalternatively-clone-the-github-repository","title":"Hint::Alternatively clone the github repository","text":"<p>You can also clone the tictactoe-cli game from GitHub</p>"},{"location":"games/tictactoe-cli/create-project/#updating-clojure-version-and-licence","title":"Updating Clojure version and licence","text":"<p>In the <code>project.clj</code> file I have updated Clojure to version 1.10.0 and changed the licence to be the more open Creative Commons license.</p> <pre><code>(defproject tictactoe-cli \"0.1.0-SNAPSHOT\"\n  :description \"TicTacToe game played on the command line\"\n  :url \"https://github.com/practicalli/tictactoe-cli\"\n  :license {:name \"Creative Commons Attribution Share-Alike 4.0 International\"\n            :url \"https://creativecommons.org\"}\n  :dependencies [[org.clojure/clojure \"1.10.0\"]])\n</code></pre> <p>I also removed the <code>license</code> file and added a brief description of the project to the <code>README.md</code> file</p> <p>{% endtabs %}</p>"},{"location":"install/","title":"Install Clojure","text":"<p>Clojure CLI provides the foundation for Clojure development, providing a declarative approach to:</p> <ul> <li>Run Clojure programs and tools</li> <li>Run a REPL process (Read-Eval-Print Loop) and provides a basic interactive terminal UI</li> <li>Manage packaged dependencies from Maven (jars) and use Git repositories as dependencies</li> </ul> <p>Practicalli Clojure Config community tools</p> <p> Practicalli Clojure CLI Config is a user configuration providing aliases for a wide range of community tools which extends the features of Clojure CLI.  The aliases include tools to create, develop, build and deploy Clojure code.  Aliases are used heavily in the Practicalli books.</p> <p>If the Practicalli Clojure CLI config is not used, review the  <code>deps.edn</code> file from the GitHub repository and add relevant aliases definitions to your own Clojure CLI configuration.</p>"},{"location":"install/#pre-requisites","title":"\"Pre-requisites\"","text":"<p>A Java Virtual Machine hosts Clojure. Java 21 is the current Long Term Support version providing a stable platform to run Clojure</p>"},{"location":"install/#additional-tools","title":"Additional tools","text":"<p>Clojure connected editor</p> <p>A Clojure connected editor provides the most effective way to write and maintain Clojure projects.  The editor connects to (or starts) a Clojure REPL and code can be evaluated as its typed, showing the results instantly in line with the code.</p> <p>Clojure LSP server generates static analysis of code which editors can surface as code diagnostics.  Analysis supports effective code navigate and refactor tools.  Practicalli Clojure LSP config configures </p> <p>Data Inspectors</p> <p>Data inspectors visualize results of Clojure code evaluation and allow navigation of nested data or paging through large data sets.</p> <p>Portal is highly recommended data inspector and included in projects generated with Practicalli Project Templates.</p> Alternative development tools <p>Leiningen is the long-standing development tool for Clojure.  All the code examples in this book should work with Leiningen when a correctly configured <code>project.clj</code> file is created which includes all the necessary library dependencies.  Libraries included via aliases should be added as either <code>:dev-dependencies</code> or <code>:aliases</code> in the Leiningen <code>project.clj</code> file.</p>"},{"location":"install/clojure-cli/","title":"Install Clojure CLI","text":"<p>Clojure CLI is a command line tool for running a Clojure REPL, project or tool.</p> <p>Clojure CLI automatically downloads required library dependencies, including the Clojure Standard library. </p> Clojure distributed as a library <p>Clojure is distributed as a library (<code>.jar</code> Java ARchive) via Maven Central. </p> <p>A <code>deps.edn</code> file specifies the version of Clojure to be used with a project.</p> <pre><code>:deps {org.clojure/clojure {:mvn/version \"1.12.0\"}}\n</code></pre> <p>The Clojure CLI tool provides a default Clojure library version if not specified in the project or user <code>deps.edn</code> files.</p> <p>Clojure releases </p> <p> Practicalli Clojure CLI Config extends the Clojure CLI with a range of development tools as well as configuration for Clojure LSP and cljstyle code format tool.</p> LinuxHomebrewWindows <p>Use the Linux script installer from Clojure.org - Getting Started to install or update to the latest stable release</p> <pre><code>curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\nsudo ./linux-install.sh\n</code></pre> <p>The installation creates <code>/usr/local/bin/clojure</code>, <code>/usr/local/bin/clj</code> wrapper and <code>/usr/local/lib/clojure</code> directory.</p> Use alternative location - unattended install <p><code>--prefix</code> option specifies an alternative lolcation for the Clojure CLI install.</p> <p>When permissions are not available or for automating the install without password prompt, use a local user specific install, e.g. <pre><code>curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\n./linux-install.sh --prefix $HOME/.local/\n</code></pre></p> Include version number for specific release <p>Each Clojure CLI version is a number that represents the version of Clojure used and the build version of the Clojure CLI tool, e.g. <code>1.11.1.1413</code>.</p> <p>Clojure CLI Releases page </p> <p>Include the version in the script name for repeatable environments, e.g. in Dockerfile configuration and Continuous Integraion workflows. Clojure CLI install specific version<pre><code>curl -L -O https://github.com/clojure/brew-install/releases/1.11.1.1413/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install-1.11.1.1413.sh\nsudo ./linux-install-1.11.1.1413.sh\n</code></pre></p> <p>Practically recommends setting <code>XDG_CONFIG_HOME</code> to the <code>.config</code> directory, to avoid creating another dot directory in the root of the user account.  Add the following to <code>~/.bashrc</code> for the bash shell or <code>~/.zshenv</code> for Zsh. <pre><code>export XDG_CONFIG_HOME=\"$HOME/.config\"\n</code></pre></p> <p>Use the Homebrew command with the clojure/tools tap, as defined in the Clojure.org Getting started guide</p> <pre><code>brew install clojure/tools/clojure\n</code></pre> <p>Use Homebrew to update an install of Clojure CLI to the latest release <pre><code>brew upgrade clojure/tools/clojure\n</code></pre></p> <p>Homebrew on Linux or Windows with WSL</p> <p>For Windows 10 use Windows Subsystem for Linux and Windows Terminal are recommended if you have administrative privileges and are comfortable using a Unix system on the command line.</p> <p>Alternatively install scoop.sh, a command line installer for windows.  Powershell 5 or greater is required. Follow the scoop-clojure getting started guide, summarized here:</p> <p>Open \"Windows PowerShell\" and enter the following commands to configure the shell:</p> <p><pre><code>iwr -useb get.scoop.sh | iex\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force\n</code></pre> Then in the same PowerShell window, install the Clojure related tools using the following commands:</p> <pre><code>scoop bucket add extras\nscoop bucket add java\nscoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure\nscoop install git 7zip pshazz temurin-lts-jdk clj-deps leiningen clj-kondo vscode coreutils windows-terminal\n</code></pre> <p>Reference: Clojure CLI Install - Clojure.org Getting Started - official guide</p>"},{"location":"install/clojure-cli/#practicalli-clojure-cli-config","title":"Practicalli Clojure CLI Config","text":"<p>Add a wide range of community tools to extend the capabilities of Clojure CLI via the aliases.</p> <p>Clone  Practicalli Clojure CLI Config GitHub repository, first removing the <code>$XDG_CONFIG_HOME/clojure</code> and <code>$HOME/.clojure</code> directory if they exist.</p> User configuration locations <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, then the user configuration is <code>$XDG_CONFIG_HOME/clojure/deps.edn</code></p> <p>Otherwise the user configuration is <code>$HOME/.clojure/deps.edn</code>.</p> <p><code>CLJ_CONFIG</code> environment variable can be used to set a custom location, overriding any other location.</p> <p>Practicalli recommends FreeDesktop XDG location</p> <p>Practically recommends setting <code>XDG_CONFIG_HOME</code> to the <code>.config</code> directory to simplify versioning of configuration. </p> <p>Configure <code>~/.bashrc</code> for the bash shell  Bash .bashrc file<pre><code>export XDG_CONFIG_HOME=\"$HOME/.config\"\n</code></pre></p> <p>Configure <code>~/.zshenv</code> for Zsh <pre><code># Set XDG_CONFIG_HOME for clean management of configuration files\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:=$HOME/.local/share}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:=$HOME/.cache}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre></p> Free Desktop XDG CONFIGClassic Config <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, clone the repository to <code>$XDG_CONFIG_HOME/clojure</code></p> <p>Via SSH <pre><code>git clone git@github.com:practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure\n</code></pre></p> <p>Via HTTPS: <pre><code>git clone https://github.com/practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure\n</code></pre></p> <p>Clojure CLI will look for its configuration in <code>$HOME/.clojure</code> directory if <code>$XDG_CONFIG_HOME</code> and <code>CLJ_CONFIG</code> environment variables not set. Via SSH ```shell git clone git@github.com:practicalli/clojure-cli-config.git $HOME/.clojure</p> <p>```</p> <pre><code>Via HTTPS\n```shell\ngit clone https://github.com/practicalli/clojure-cli-config.git $HOME/.clojure\n```\n</code></pre>"},{"location":"install/clojure-cli/#check-configuration","title":"Check Configuration","text":"<p><code>clojure -Sdescribe</code> shows the version of Clojure CLI installed and configuration locations used.</p> <pre><code>clojure -Sdescribe\n</code></pre> <p>The output of the command includes the version of Clojure CLI in the <code>:version</code> key</p> <pre><code>{:version \"1.11.1.1386\"\n :config-files [\"/usr/local/lib/clojure/deps.edn\" \"/home/practicalli/.config/clojure/deps.edn\" ]\n :config-user \"/home/practicalli/.config/clojure/deps.edn\"\n :config-project \"deps.edn\"\n :install-dir \"/usr/local/lib/clojure\"\n :config-dir \"/home/practicalli/.config/clojure\"\n :cache-dir \"/home/practicalli/.cache/clojure\"\n :force false\n :repro false\n :main-aliases \"\"\n :repl-aliases \"\"}\n</code></pre> <p><code>clojure -Sversion</code> will shows the version of Clojure CLI being when the <code>clojure</code> command is used to run a REPL or other Clojure command.</p>"},{"location":"install/clojure-cli/#optional-rlwrap-readline","title":"Optional rlwrap readline","text":"<p>The <code>rlwrap</code> binary is a basic readline tool that provides a history of commands entered into a terminal UI when running a Clojure REPL with the <code>clj</code> wrapper script.</p> <p>Pressing the Up and Down keys will scroll through the code previously entered in the REPL.</p> <p><code>rlwrap</code> is available with most Linux systems. Look for  install instructions by searching for rlwrap in a web browser or build from source from the  rlwrap GitHub repository.</p> <p>Use Rebel Readline for a rich terminal UI experience</p> <p> rebel readline is an advanced readline tool providing auto-completion, documentation, signature help and multi-line editing, all within a terminal UI</p> <p>Rebel is a much richer experience than the <code>clj</code> wrapper with <code>rlwrap</code>.  Rebel should not be used with <code>clj</code>.</p> <p>Rebel Readline is part of the Practicalli Clojure CLI config.</p>"},{"location":"install/java/","title":"Java Host","text":"<p>Java is a host platform for Clojure, on which Clojure projects and tools run.  Java provides a virtual machine which runs the bytecode generated when Clojure code is compiled.</p> <p>Java virtual machine includes a Just In Time (JIT) compiler that optimises running of bytecode.</p> <p>Practicalli recommends OpenJDK version 21</p>"},{"location":"install/java/#install-java","title":"Install Java","text":"<p>Check to see if there is an appropriate version of Java already installed.</p> <p>Open a terminal and run the command</p> <pre><code>java --version\n</code></pre> <p>If Java is installed and on the execution path, the version infomation is returned</p> <p> </p> Debian PackagesHomebrewWindowsManual <p>Install Java development kit (JDK) using the <code>apt</code> package manager (login as <code>su -</code> or prefix the command with <code>sudo</code>)</p> <pre><code>apt install openjdk-21-jdk\n</code></pre> Check available versions of OpenJDK <p>Long terms support versions should include OpenJDK 17 and may include OpenJDK 21.  Check versions available via the <code>apt</code> package management tool.</p> <pre><code>apt search --names-only openjdk\n</code></pre> Optionally include Java docs and sources <p>Install the <code>openjdk-21-doc</code> locally to provide Javadocs to support Java Interop code.</p> <p>Install the <code>openjdk-21-source</code> package to support navigation of Java Object and Method source code, especially useful when using Java Interoperability from within Clojure code.</p> <pre><code>sudo apt install openjdk-21-doc openjdk-21-source\n</code></pre> <p> Practicalli Clojure CLI Config provides the <code>:src/java17</code> alias to include the Java sources in the classpath when running a REPL.</p> <p>If <code>openjdk-21-jdk</code> package is not available, add the Ubuntu OpenJDK personal package archive</p> <pre><code>sudo add-apt-repository ppa:openjdk-r/ppa\nsudo apt-get update\n</code></pre> <p>When multiple versions of Java are installed, set the version using the <code>update-alternatives</code> command in a terminal</p> <pre><code>sudo update-alternatives --config java\n</code></pre> <p>Available java versions will be listed.  Enter the list number for the version you wish to use.</p> <p>Using Homebrew, run the following command in a terminal to install Java 17:</p> <pre><code>brew install openjdk@21\n</code></pre> Switching between Java versions <p>More than one version of Java can be installed on MacOSX. Set the Java version by opening a terminal and using one of the following commands</p> <p>Show the Java versions installed <pre><code>/usr/libexec/java_home -V\n</code></pre></p> <p>Switch to Java version 21 <pre><code>export JAVA_HOME=$(/usr/libexec/java_home -v 21)\n</code></pre></p> <p>Alternatively, install JEnv Java version manager</p> <p>For Windows 10 use Windows Subsystem for Linux and Windows Terminal are recommended if you have administrative privileges and are happy to use a Unix system on the command line.</p> <p>Alternatively use scoop.sh, a command line installer for windows.  Powershell 5 or greater is required.</p> <p>Follow the scoop-clojure install instructions, summarized here:</p> <pre><code>scoop bucket add java\nscoop install temurin-lts-jdk\n</code></pre> <p>scoop can also be used to install clojure</p> <p>If neither Scoop or Windows Subsystem for Linux work, try the Chocolatey package manager. Install the Java Runtime (JRE) using the following command in a command line window</p> <pre><code>choco install javaruntime\n</code></pre> <p>If Chocolatey does not work, then try the manual Java install.</p> <p>Download OpenJDK from Adoptium - pre-build OpenJDK binaries freely available for multiple operating systems.</p> <p>Run the file once downloaded and follow the install instructions.</p> <p></p>"},{"location":"install/java/#multiple-versions-of-java","title":"Multiple versions of Java","text":"<p> jenv provides a simple way to switch between multiple installed versions of Java.  jenv can be used to set the java version globally, for the current shell or for a specific project by adding <code>.java-version</code> file containing the Java version number in the root of the project.</p>"},{"location":"install/java/#a-little-java-knowledge","title":"A little Java Knowledge","text":"<p>Very little knowledge of the Java language or the Java Virtual Machine is required.</p> <p>It is quite simple to call Java methods from Clojure, although there are a wealth of functions and libraries provided by Clojure and its community to minimise the need for Java Interoperability.</p> <p>Reading stack traces may benefit from some Java experience, although its usually the first couple of lines in a stack trace that describe the issue.</p> <p>Clojure uses its own build tools (Leiningen, Clojure CLI tools) and so Java build tool knowledge is not required.</p> <p>When libraries are added to a project, they are downloaded to the <code>$HOME/.m2</code> directory.  This is the default Maven cache used by all JVM libraries.</p> <p><code>clojure  -Spom</code> will generate a Maven pom.xml file used for deployment. Understanding of a minimal Maven POM (pom.xml) file is useful when managing issues with packaging and deployment.</p> <p>Maven in 5 minutes</p> <p>The Java Virtual Machine is highly optimised and does not usually require any options to enhance its performance. The most likely configuration to supply to the JVM are to manage the amount of memory assigned, specifically for resource constrained environments.</p>"},{"location":"introduction/clojure-in-15-minutes/","title":"Clojure in 15 minutes","text":"<p>A quick tour of the Clojure syntax and common functions, which is so terse you can read through this page in around 15 minutes and have a basic understanding of the language.</p> <p>Try the code out in the REPL</p> <p> Start a Clojure REPL or use a  Clojure aware editor connected to a REPL and experiment with these code examples.</p> <p>Using the REPL provides instant feedback on each expression as they are evaluated, greatly increasing your understanding.</p>"},{"location":"introduction/clojure-in-15-minutes/#comments","title":"Comments","text":"<p><code>;;</code> two semi-colons for a line comment, <code>;</code> single semi-colon to comment the rest of the line</p> <p><code>#_</code> comment reader macro to comment out the next form</p> <p><code>(comment ,,,)</code> form to comment all the containing forms, useful to  separate experimental and established code in a namespace.</p>"},{"location":"introduction/clojure-in-15-minutes/#clojure-expressions","title":"Clojure expressions","text":"<p>Clojure is mostly written with \"expressions\", a lists of elements inside parentheses, <code>()</code>, separated by space characters.</p> <p>Clojure evaluates the first element in an expression as a function call.  Additional elements in the expression are passed as value arguments to the called function.</p> <p>Function call with value and expression as arguments</p> <pre><code>(+ 2007 (* 1 16))\n</code></pre> <p>Functions can be passed as an argument</p> <pre><code>(map inc (range 0 99))\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#organising-clojure","title":"Organising Clojure","text":"<p>Clojure code is organised into one or more namespaces. The namespace represents the directory path and file name that contains the code of the particular namespace.</p> <p>A company name or community repository name is often used making the namespace unique and easier to share &amp; reuse.</p> ns form returns nil value <p>The <code>(ns namespace.,,,)</code> expression returns a <code>nil</code> value, as its work is done behind the scenes.</p> <p>All Clojure functions must return a value and <code>nil</code> is a value that means 'no value'.</p> <p>Define a namespace</p> src/practicalli/game_board.clj<pre><code>(ns practicalli.game-board)\n</code></pre> <p>Define a longer namespace</p> src/com/company/product/component_name.clj<pre><code>(ns com.company.product.component-name)\n</code></pre> Namespaces use dash, directory and file names use underscore <p>Clojure uses <code>kebab-case</code> for names (common in Lisp dialects)</p> <p>Unfortunately the Java Virtual Machine that hosts Clojure does not support dash, <code>-</code>, in file and directory names, so an underscore, <code>-</code>, character is used</p>"},{"location":"introduction/clojure-in-15-minutes/#string-manipulation","title":"String manipulation","text":"<p>The <code>str</code> function creates a new string from all the arguments passed</p> <p>Combine strings into a single string value</p> <pre><code>(str \"Hello\" \" \" \"World\")\n</code></pre> <p><code>\"Hello World\"</code> is returned from evaluating the expression.</p> <p>clojure.string library for manipulating strings</p> <p><code>clojure.string</code> library functions manipulate values and return string values (other clojure.core functions my return characters as results, e.g. <code>map</code>)</p>"},{"location":"introduction/clojure-in-15-minutes/#math-truth-prefix-notation","title":"Math, Truth &amp; prefix notation","text":"<p>Functions use prefix notation, so you can do math with multiple values very easily</p> <p>Prefix syntax takes multiple arguments</p> <pre><code>(+ 1 2 3 5 7 9 12) ; =&gt; 40\n</code></pre> <p>Math in Clojure is very precise, no need for operator precedence rules (as there are no operators)</p> <p>Nesting forms defined a very precise calculation</p> <p>Parentheses used instead of operator preceedence rules</p> <pre><code>(* 1 2 (- 24 (* 7 3)))\n</code></pre> <p><code>6</code> is returned as the value.  Nested expressions are typically read inside out.  <code>(* 7 3)</code> is <code>21</code>, giving <code>(- 24 21)</code> expression resulting in <code>3</code>.  Finally the expression becomes <code>(* 1 2 3)</code>, resulting in a value of <code>6</code></p> <p>Maintain precision for calculations using a Ratio type in Clojure</p> <p>Clojure Ratio value</p> <pre><code>(/ 27 7)  ; =&gt; 27/7\n</code></pre> <p><code>22/7</code> is returned as the value, rather than a floating point value (double) which may loose some precision due to rounding.</p>"},{"location":"introduction/clojure-in-15-minutes/#equality","title":"Equality","text":"<p><code>=</code> function provides a test for equality</p> <p>Equal values return a boolean true</p> <pre><code>(= 1 1) ; =&gt; true\n</code></pre> <p>Unequals values return a boolean false</p> <pre><code>(= 2 1) ; =&gt; false\n</code></pre> <p><code>true</code> and <code>false</code> are Boolean values and can be used literally in Clojure.</p>"},{"location":"introduction/clojure-in-15-minutes/#predicates","title":"Predicates","text":"<p>A predicate is a function that returns a boolean <code>true</code> or <code>false</code> value and by convention the function name ends in <code>?</code>, e.g. <code>true?</code>, <code>false?</code>, <code>seq?</code>, <code>even?</code>, <code>uuid?</code>.</p> <p><code>and</code> &amp; <code>or</code> functions can be used to chain the results of predicates together for more interesting conditional tests.</p> <p>All predicates are true, returning true</p> <pre><code>(and (true? true) (not false)) ; =&gt; true\n</code></pre> <p>One of the predicates or values is true</p> <pre><code>(or nil (not= true false) (true? (complement true?)) ) ; =&gt; true\n</code></pre> <p>Truthy and Falsy values in Clojure</p> <p><code>false</code> boolean value and <code>nil</code> value are considered false in Clojure.</p> <p>All other values are consider true.</p> <p> Clojure Standard Library Predicate Functions</p>"},{"location":"introduction/clojure-in-15-minutes/#collections-sequences","title":"Collections &amp; Sequences","text":"<p>The most common data collections in Clojure:</p> <ul> <li><code>(1 2 \"three\")</code> or <code>(list 1 2 \"three\")</code> - a list of values read from start to end (sequential access)</li> <li><code>[1 2 \"three\"]</code> or <code>(list 1 2 \"three\")</code> - a vector of values with index (random access)</li> <li><code>{:key \"value\"}</code> or <code>(hash-map :key \"value\")</code> - a hash-map with zero or more key value pairs (associative relation)</li> <li><code>#{1 2 \"three\"}</code> or <code>(set 1 2 \"three\")</code> - a unique set of values</li> </ul> <p>A list <code>()</code> is evaluated as a function call. The first element of the list the name of the function to call and additional values are arguments to the function.</p> <p>The <code>'</code> quote function informs the Clojure reader to treat the list as data only.</p> <p>A quoted list is treated as data</p> <pre><code>'(1 2 3) ; =&gt; (1 2 3)\n</code></pre> <p>Lists and vectors are collections</p> <pre><code>(and (coll? '(1 2 3)) (coll? [1 2 3])) ; =&gt; true\n</code></pre> <p>Only lists are sequences</p> <pre><code>(seq? '(1 2 3)) ; =&gt; true\n(seq? [1 2 3]) ; =&gt; false\n</code></pre> <p>Sequences are an interface for logical lists, which can be lazy. \"Lazy\" means that a sequence of values are not evaluated until accessed.</p> <p>A lazy sequence enables the use of large or even an infinite series, like so:</p> <p>Lazy sequences</p> <pre><code>(range) ; =&gt; (0 1 2 3 4 ...) - an infinite series\n(take 4 (range)) ;  (0 1 2 3) - lazyily evaluate range and stop when enough values are taken\n</code></pre> <p>Use cons to add an item to the beginning of a list or vector</p> <pre><code>(cons 4 [1 2 3]) ; =&gt; (4 1 2 3)\n(cons 4 '(1 2 3)) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use conj to add an item relative to the type of collection, to the beginning of a list or the end of a vector</p> <pre><code>(conj [1 2 3] 4) ; =&gt; [1 2 3 4]\n(conj '(1 2 3) 4) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use concat to add lists or vectors together</p> <pre><code>(concat [1 2] '(3 4)) ; =&gt; (1 2 3 4)\n</code></pre> <p>Use filter, map to interact with collections</p> <pre><code>(map inc [1 2 3]) ; =&gt; (2 3 4)\n(filter even? [1 2 3]) ; =&gt; (2)\n</code></pre> <p>Use reduce to reduce them</p> <pre><code>(reduce + [1 2 3 4])\n; = (+ (+ (+ 1 2) 3) 4)\n; =&gt; 10\n</code></pre> <p>Reduce can take an initial-value argument too</p> <pre><code>(reduce conj [] '(3 2 1))\n; =&gt; [3 2 1]\n</code></pre> <p>Equivalent of <code>(conj (conj (conj [] 3) 2) 1)</code></p>"},{"location":"introduction/clojure-in-15-minutes/#annonymous-functions","title":"Annonymous Functions","text":"<p>Use <code>fn</code> to create new functions that defines some behaviour. <code>fn</code> is referred to as an anonymous fuction as it has no external name to be referenced by and must be called within a list form.</p> <pre><code>(fn hello [] \"Hello World\")\n</code></pre> <p>Wrap a <code>(fn ,,,)</code> form in parens to call it and return the result.</p> <p>Call an anonymous function</p> <pre><code>((fn hello [] \"Hello World\")) ; =&gt; \"Hello World\"\n</code></pre> <p>Normally the anonymous function is used inline with other code</p> <p>Use anonymous function within other code</p> <pre><code>(map (fn [x] (* x 2)) [1 2 3 4  [1 2 3 4 5]5])\n</code></pre> <p>Make the anonymous function reusable by binding it to a shared name (<code>var</code>) using <code>def</code>.</p> <p>The <code>var</code> name bound to the function can now be called anywhere in the namespace.</p> <p>As <code>def</code> creates a <code>var</code> (variable) name, the developer can changed the expression the name is bound to and re-evaluated to use the changed behaviour.</p> <p>Bind a name to the anonymous function</p> <pre><code>(def hello-world\n  (fn hello [] \"Hello World\"))\n</code></pre> <p>Evaluate annonymous function by evaluating its name</p> <pre><code>hello-world\n</code></pre> <p>NOTE: <code>hello-world</code> is a name and not a function call, so parentheses are not required.</p>"},{"location":"introduction/clojure-in-15-minutes/#shared-functions","title":"Shared Functions","text":"<p>It is more common to use the <code>defn</code> macro to define a function.  This is the same as defining the <code>fn</code> function and the <code>def</code> name within the same expression</p> <p>Define a function with defn macro</p> <pre><code>(defn hello-world\n  \"I am a humble doc-string, please describe the function purpose\"\n []\n \"Hello World\")\n</code></pre> <p><code>#'user/hello-world</code> is the value returned from evaluating the expression, showing the fully qualified name of the function.  Note: the fully qualified name will be different when defined in a differnt namespace than <code>user</code>.</p> <p>A <code>defn</code> function has the scope of the current namespace, so can be called anywhere in the namespace or in a namepace that has used <code>require</code> to include this namespace.</p> <p>Call a function</p> <pre><code>(hello-world)\n</code></pre> <p>The <code>[]</code> vector is used to define the argument names for the function.  There can be zero or more arguments.</p> <p>Call function with arguments</p> <pre><code>(defn hello [name]\n  (str \"Hello \" name))\n</code></pre> <p>The correct number of arguments must be used when calling a function, or an error will be returned.</p> <p>Call function with arguments</p> <pre><code>(hello \"Steve\") ; =&gt; \"Hello Steve\"\n</code></pre> Pass a hash-map as an argument <p>Simplify the design of a function signature by passing all arguments as a hash-map. <pre><code>(defn data-processing\n  [data]\n  (let [body (get data :body)])\n    (transform body))\n</code></pre>  Associative Destructuring can be used to automatically create local variables from the desired keys contained in the map, giving access to the value of each key. <pre><code>(defn data-processing\n  [{:keys [body]}]\n  (transform body))\n</code></pre></p> <p>Clojure supports  multi-variadic functions, allowing one function definition to respond to a function call with different number of arguments.  This provides a simple form of polymorphism based on the number of arguments.</p> <pre><code>(defn hello-polly\n  ([] \"Hello World\")  ; (1)!\n  ([name] (str \"Hello \" name))) ; (2)!\n</code></pre> <ol> <li> <p>Call <code>hello-polly</code> with one argument      <pre><code>(hello-polly \"Jake\") ; =&gt; \"Hello Jake\"\n</code></pre></p> </li> <li> <p>Call <code>hello-polly</code> with zero arguments      <pre><code>(hello-polly) ; =&gt; \"Hello World\"\n</code></pre></p> </li> </ol> <p>Functions can pack extra arguments up in a seq for you</p> <pre><code>(defn count-args [&amp; args]\n  (str \"You passed \" (count args) \" args: \" args))\n(count-args 1 2 3) ; =&gt; \"You passed 3 args: (1 2 3)\"\n</code></pre> <p>You can mix regular and packed arguments</p> <pre><code>(defn hello-count [name &amp; args]\n  (str \"Hello \" name \", you passed \" (count args) \" extra args\"))\n(hello-count \"Finn\" 1 2 3)\n; =&gt; \"Hello Finn, you passed 3 extra args\"\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#hash-map-collections","title":"Hash-map collections","text":"<pre><code>(class {:a 1 :b 2 :c 3}) ; =&gt; clojure.lang.PersistentArrayMap\n</code></pre> <p>Keywords are like strings with some efficiency bonuses</p> <pre><code>(class :a) ; =&gt; clojure.lang.Keyword\n</code></pre> <p>Maps can use any type as a key, but usually keywords are best</p> <pre><code>(def stringmap (hash-map \"a\" 1, \"b\" 2, \"c\" 3))\nstringmap  ; =&gt; {\"a\" 1, \"b\" 2, \"c\" 3}\n\n(def keymap (hash-map :a 1 :b 2 :c 3))\nkeymap ; =&gt; {:a 1, :c 3, :b 2} (order is not guaranteed)\n</code></pre> Commas are whitespace <p>commas are always treated as whitespace and are ignored by the Clojure reader</p> <p>Retrieve a value from a map by calling it as a function</p> <pre><code>(stringmap \"a\") ; =&gt; 1\n(keymap :a) ; =&gt; 1\n</code></pre> <p>Keywords can be used to retrieve their value from a map.  Strings cannot be used.</p> <pre><code>(:b keymap) ; =&gt; 2\n\n(\"a\" stringmap)\n; =&gt; Exception: java.lang.String cannot be cast to clojure.lang.IFn\n</code></pre> <p>Retrieving a non-present value returns nil</p> <pre><code>(stringmap \"d\") ; =&gt; nil\n</code></pre> <p>Use assoc to add new keys to hash-maps</p> <pre><code>(assoc keymap :d 4) ; =&gt; {:a 1, :b 2, :c 3, :d 4}\n</code></pre> <p>But remember, clojure types are immutable!</p> <pre><code>keymap ; =&gt; {:a 1, :b 2, :c 3}\n</code></pre> <p>Use dissoc to remove keys</p> <pre><code>(dissoc keymap :a :b) ; =&gt; {:c 3}\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#sets","title":"Sets","text":"<pre><code>(class #{1 2 3}) ; =&gt; clojure.lang.PersistentHashSet\n(set [1 2 3 1 2 3 3 2 1 3 2 1]) ; =&gt; #{1 2 3}\n</code></pre> <p>Add a member with conj</p> <pre><code>(conj #{1 2 3} 4) ; =&gt; #{1 2 3 4}\n</code></pre> <p>Remove one with disj</p> <pre><code>(disj #{1 2 3} 1) ; =&gt; #{2 3}\n````\n\nTest for existence by using the set as a function:\n\n```clojure\n(#{1 2 3} 1) ; =&gt; 1\n(#{1 2 3} 4) ; =&gt; nil\n</code></pre> <p>There are more functions in the clojure.sets namespace.</p>"},{"location":"introduction/clojure-in-15-minutes/#useful-forms","title":"Useful forms","text":"<p>Logic constructs in clojure are just macros, and look like everything else</p> <pre><code>(if false \"a\" \"b\") ; =&gt; \"b\"\n(if false \"a\") ; =&gt; nil\n</code></pre> <p>Use let to create temporary bindings</p> <pre><code>(let [a 1 b 2]\n  (&gt; a b)) ; =&gt; false\n</code></pre> <p>Group statements together with do</p> <pre><code>(do\n  (print \"Hello\")\n  \"World\") ; =&gt; \"World\" (prints \"Hello\")\n</code></pre> <p>Functions have an implicit do</p> <pre><code>(defn print-and-say-hello [name]\n  (print \"Saying hello to \" name)\n  (str \"Hello \" name))\n(print-and-say-hello \"Jeff\") ;=&gt; \"Hello Jeff\" (prints \"Saying hello to Jeff\")\n</code></pre> <p>So does let</p> <pre><code>(let [name \"Urkel\"]\n  (print \"Saying hello to \" name)\n  (str \"Hello \" name)) ; =&gt; \"Hello Urkel\" (prints \"Saying hello to Urkel\")\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#namespaces-and-libraries","title":"Namespaces and Libraries","text":"<p>Namespaces are used to organise code into logical groups.  The top of each Clojure file has an <code>ns</code> form that defines the namespace name.  The domain part of the namespace name is typically the organisation or community name (e.g. GitHub user/organisation)</p> <pre><code>(ns domain.namespace-name)\n</code></pre> <p>All Practicalli projects have namespace domains of <code>practicalli</code></p> <pre><code>(ns practicalli.service-name)\n</code></pre> <p><code>require</code> allows code from one namespace to be accessed from another namespace, either from a the same Clojure project or from a library added to the project classpath.</p> <p>The <code>:as</code> directive with <code>require</code> is used to specify an alias name, a short-hand for the full library name</p> <p>Or <code>:refer [function-name var-name]</code> can be used to specify specific functions and data (vars) that are available directly</p> <p>A required directive is typically added to a namespace form</p> <pre><code>(ns practicalli.service-name\n  (require [clojure.set :as set]))\n</code></pre> <p>The functions from clojure.set can be used via the alias name, rather than the fully qualified name, i.e. <code>clojure.set/intersection</code></p> <pre><code>(set/intersection #{1 2 3} #{2 3 4}) ; =&gt; #{2 3}\n(set/difference #{1 2 3} #{2 3 4}) ; =&gt; #{1}\n</code></pre> <p><code>:require</code> directive can be used to include multiple library namespaces</p> <pre><code>(ns test\n  (:require\n    [clojure.string :as string]\n    [clojure.set :as set]))\n</code></pre> <p><code>require</code> can be used by itself, usually within a rich code block</p> <pre><code>(comment\n  (require 'clojure.set :as set))\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#strong-dynamic-types","title":"Strong Dynamic Types","text":"<p>Clojure is strongly typed, so everything is a type in Clojure.</p> <p>Clojure is dynamically typed, so Clojure infers the type.  A type does not need to be specified in the code, making the code simpler and more concise.</p> <p>Clojure is a hosted language and uses the type system of the platform it runs upon.  For example, Clojure uses Java object types for booleans, strings and numbers under the covers.</p> <p>Use <code>class</code> or <code>type</code> function to inspect the type of some code in Clojure.</p> <pre><code>(type 1) ; Integer literals are java.lang.Long by default\n(type 1.); Float literals are java.lang.Double\n(type \"\"); Strings always double-quoted, and are java.lang.String\n(type false) ; Booleans are java.lang.Boolean\n(type nil); The \"null\" value is called nil\n</code></pre> <p>Vectors and Lists are java classes too!</p> <pre><code>(type [1 2 3]); =&gt; clojure.lang.PersistentVector\n(type '(1 2 3)); =&gt; clojure.lang.PersistentList\n</code></pre> <p>Type hints</p> <p>Type hints can be used to avoid reflection look-ups where performace critical issues have been identified.  Type hints are not required in general. Clojure Type Hints</p>"},{"location":"introduction/clojure-in-15-minutes/#java-interop","title":"Java Interop","text":"<p>Java has a huge and useful standard library, so you'll want to learn how to get at it.</p> <p>Use import to load a java package</p> <pre><code>(import java.util.Date)\n</code></pre> <p>Or import from a java package name</p> <pre><code>(ns test\n  (:import\n    java.util.Date\n    java.util.Calendar))\n</code></pre> <p>Use the class name with a \".\" at the end to make a new instance</p> <pre><code>(Date.) ; &lt;a date object&gt;\n</code></pre> <p>Use <code>.</code> to call methods. Or, use the \".method\" shortcut</p> <pre><code>(. (Date.) getTime) ; &lt;a timestamp&gt;\n(.getTime (Date.))  ; exactly the same thing.\n</code></pre> <p>Use / to call static methods</p> <pre><code>(System/currentTimeMillis) ; &lt;a timestamp&gt; (system is always present)\n</code></pre> <p>Use doto to make dealing with (mutable) classes more tolerable</p> <pre><code>(import java.util.Calendar)\n(doto (Calendar/getInstance)\n  (.set 2000 1 1 0 0 0)\n  .getTime) ; =&gt; A Date. set to 2000-01-01 00:00:00\n</code></pre>"},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"<p>By submitting content ideas and corrections you are agreeing they can be used in any work by Practicalli under the Creative Commons Attribution ShareAlike 4.0 International license.  Attribution will be detailed via GitHub contributors.</p> <p>Please raise an issue before creating a pull request</p> <p>Raising an issue or post on the #practicalli channel of Clojurians Slack community avoids disappointment if the contribution would not be accepted and saves time for all.</p> <p>Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow.  MkDocs can also run a local server using the <code>make docs</code> target from the <code>Makefile</code></p> <p>All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.</p>"},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"<p>If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.</p> <p>Raising an issue before creating a pull request will save you and the maintainer time.</p> <p>Alternatively, reach out to Practicalli via the <code>#practicalli</code> channel of the Clojurians Slack community.</p> <p>Clojurians Slack community</p>"},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"<p>Pull Request Commits must be cryptographically signed</p> <p>All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.</p> <p>Configure commit signing with SSH key - Practicalli Engineering</p> <p>All pull requests must include an entry in CHANGELOG.md or will not be merged.  A changelog entry allows the community to follow the changes to the book.</p> <p>Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.</p> <p>Please keep pull requests small and focused, as they are much quicker to review and easier to accept.  Ideally PR's should be for a specific page or at most a section.</p> <p>A PR with a list of changes across different sections will be closed without merging as these take considerable time to review.</p> <p>Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged.  Raise an issue, or post a thread in the  Clojurians Slack #practicall channel</p>"},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"<p>A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language.  </p> <p>The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions.  I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.</p> <p>Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.</p> <p>Special thanks to Bruce Durling for getting me into Cloure in the first place.</p> <p></p>"},{"location":"introduction/first-taste-of-clojure/","title":"Clojure Quick Reference","text":"<p>The basic Clojure syntax and a few common functions you should probably learn first.</p> <p>The examples are editable (using an embedded REPL) so feel free to experiment and watch as the return value changes as you change the code.  Reload the page if you want to reset all the code back to the starting point.</p> <p>Install Clojure on your computer if you want to experiment even further.</p> <p>Want to go deeper already?</p> <p>Watch the Clojure language video series by Brian Will for a detailed introduction to key parts of the language.  Or discover Clojure core functions by completing challenges on 4Clojure.org and then watching how Practicalli solved them.</p>"},{"location":"introduction/first-taste-of-clojure/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is a call to a function.  Any other elements are passed to the function as arguments. The examples show how to call functions with multiple arguments.</p> <pre><code>(+ 1 2)\n</code></pre> <pre><code>(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n</code></pre> <pre><code>(str \"Clojure is \" (- 2021 2007) \" years old\")\n</code></pre> <pre><code>(inc 1)\n</code></pre> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <pre><code>(filter odd? (range 11))\n</code></pre> <p>Prefix notation and parens</p> <p>Hugging code with <code>()</code> is a simple syntax to define the scope of code expressions.  No additional <code>;</code>, <code>,</code> or spaces are required.</p> <p>Treating the first element of a list as a function call is referred to as prefix notation, which greatly simplifies Clojure syntax.  Prefix notation makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p>"},{"location":"introduction/first-taste-of-clojure/#understanding-functions","title":"Understanding functions","text":"<p><code>clojure.repl/doc</code> function returns the doc-string of the given function. A doc-string should be part of all public function definitions.</p> <p>Clojure editors should provide commands to view doc-strings and the ability to jump to function definitions to view their source code</p> <pre><code>(clojure.repl/ddoc doc)\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <p>A list, <code>()</code>, used for calling functions and representing sequences. A linked list for sequential access.</p> <pre><code>(str \"lists used mainly \" (* 2 2) \" \" :code)\n</code></pre> <p>A vector, <code>[]</code>, used for simple collections of values.  An indexed data structure for random access</p> <pre><code>[0 \"indexed\" :array (* 2 2) \"random-access\" 4 :data]\n</code></pre> <p>A map, <code>{}</code>, use for descriptive data collections.  An associative data structure for value lookup by unique keys (also known as a dictionary).</p> <pre><code>{ :hash-map :associative-collection :pairs {:key \"value\"} :aka \"dictionary\"}\n</code></pre> <p>A set, <code>#{}</code>, use as a unique set of values. Sets are used to test if a value is contained within, i.e. predicates.</p> <pre><code>#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre> <p>Persistent data types</p> <p>Values are immutable so when a function changes a value a new immutable value is created. When creating new collection values, unchanged values are shared with the original collection.  This sharing model is called persistent data types and enables immutable data to be used efficiently.</p>"},{"location":"introduction/first-taste-of-clojure/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p> <p><code>map</code> <code>reduce</code> <code>filter</code> are common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n</code></pre> <pre><code>(filter even? [1 3 5 8 13 21 34])\n</code></pre> <pre><code>(reduce + [31 28 30 31 30 31])\n</code></pre> <pre><code>(empty? [])\n</code></pre> <p>Many Clojure core functions for collections</p> <p><code>map</code>, <code>reduce</code>, <code>apply</code>, <code>filter</code>, <code>remove</code> are just a few examples of Clojure core functions that work with data structures.</p>"},{"location":"introduction/first-taste-of-clojure/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(map (fn [number] (* number number)) [1 2 3 4 5])\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#defining-local-names","title":"Defining local names","text":"<p>Use the <code>let</code> function as a simple way to experiment with code designs</p> <pre><code>(let [data (range 24 188)\n      total (reduce + data)\n      values (count data)]\n  (str \"Average value: \" (/ total values)))\n</code></pre> <p>Define local names to remove duplication in function definitions, or to simplify algorithms</p> <pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>A name bound to a value can be used to represent that value throughout the code.  Names can be bound to simple values (numbers, strings, etc.), collections or even function calls.</p> <p><code>def</code> binds a name to a value with the scope of the current namespace.  <code>def</code> is useful for data that is passed to multiple functions within a namespace.</p> <p>Evaluating a name will return the value it is bound to.</p> <pre><code>(def public-health-data\n  [{:date \"2020-01-01\" :confirmed-cases 23814 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 24329 :recovery-percent 14}\n   {:date \"2020-01-03\" :confirmed-cases 25057 :recovery-percent 12}])\n\npublic-health-data\n</code></pre> <p>def for shared values, let for locally scoped values</p> <p><code>let</code> function is used to bind names to values locally, such as within a function definition.  Names bound with <code>def</code> have namespace scope so can be used with any code in that namespace.</p>"},{"location":"introduction/first-taste-of-clojure/#iterating-over-collections","title":"Iterating over collections","text":"<p><code>map</code> iterates a function over a collection of values, returning a new collection of values</p> <pre><code>(map inc (range 20))\n</code></pre> <p><code>reduce</code> iterates a function over the values of a collection to produce a new result</p> <pre><code>(reduce + (range 101))\n</code></pre> <p>Reducing functions are function definitions used by the <code>reduce</code> function over a collection</p> <pre><code>(reduce (fn [[numerator denominator] accumulator]\n          [(+ numerator accumulator)\n           (inc denominator)])\n        [0 0]\n        (range 1 20))\n</code></pre> <p>Functions can call themselves to iterate over a collection.  Using a lazy sequence means only the required numbers are generated, ensuring efficiency of operation and making the function usable in many different scenarios.</p> <pre><code>(defn fibonacci-sequence\n  [current-number next-number]\n  (lazy-seq\n    (cons current-number\n          (fibonacci-sequence next-number (+ current-number next-number)))))\n\n(take 10 (fibonacci-sequence 0 1))\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#host-interoperability","title":"Host Interoperability","text":"<p>The REPL in this web page is running inside a JavaScript engine, so JavaScript functions can be used from within ClojureScript code (ClojureScript is Clojure that runs in JavaScript environments).</p> <p>In the box below, replace <code>()</code> with <code>(js/alert \"I am a pop-up alert\")</code></p> <pre><code>()\n</code></pre> <p>Java libraries in Clojure</p> <p>java.lang library is available in Clojure by default and many other Java methods can be included by using their full name, e.g. <code>(java.lang.Date.)</code> will return the current date.</p>"},{"location":"introduction/first-taste-of-clojure/#next-steps","title":"Next steps","text":"<p>Install Clojure on your computer if you want to experiment even further or keep on reading more about Clojure.</p>"},{"location":"introduction/five-steps-to-clojure/","title":"5 Steps to Clojure","text":""},{"location":"introduction/five-steps-to-clojure/#set-up-your-environment","title":"Set up your environment","text":"<p>Install Clojure and a build tool</p> <p>Setup a Clojure aware editor</p> <ul> <li>Emacs &amp; CIDER - Spacemacs, Doom, Prelude</li> <li>Neovim &amp; Conjure</li> <li>VSCode &amp; Clover or Calva</li> <li>Sublime Text &amp; SublimedClojure</li> </ul>"},{"location":"introduction/five-steps-to-clojure/#learn-the-syntax","title":"Learn the syntax","text":""},{"location":"introduction/five-steps-to-clojure/#practice-the-core-functions","title":"Practice the core functions","text":"<ul> <li>4clojure.org</li> <li>Exercism.io</li> </ul>"},{"location":"introduction/five-steps-to-clojure/#def-defn-let","title":"def / defn / let","text":""},{"location":"introduction/five-steps-to-clojure/#map-reduce-apply","title":"map / reduce / apply","text":""},{"location":"introduction/five-steps-to-clojure/#for-while-loop-recur","title":"for / while / loop / recur","text":""},{"location":"introduction/five-steps-to-clojure/#adopt-functional-programming-practices","title":"Adopt functional programming practices","text":""},{"location":"introduction/five-steps-to-clojure/#learn-the-commonly-used-libraries","title":"Learn the commonly used libraries","text":""},{"location":"introduction/five-steps-to-clojure/#server-side-websites","title":"Server-side websites","text":""},{"location":"introduction/five-steps-to-clojure/#ring-compojure-reitit-hiccup-selma","title":"Ring / Compojure / Reitit / Hiccup | Selma","text":""},{"location":"introduction/five-steps-to-clojure/#react-client-side-single-page-apps","title":"React client-side single page apps","text":""},{"location":"introduction/five-steps-to-clojure/#reactjs-om-next-reagent-re-frame","title":"React.js / Om-next / Reagent / Re-frame","text":""},{"location":"introduction/five-steps-to-clojure/#coreasync","title":"core.async","text":""},{"location":"introduction/five-steps-to-clojure/#full-stack-apps","title":"Full Stack apps","text":""},{"location":"introduction/five-steps-to-clojure/#kit-framework","title":"Kit Framework","text":""},{"location":"introduction/learning-clojure/","title":"Learning Clojure","text":"<p>Learning the syntax of Clojure is really quick (its very small and simple).  Learning to think functionally and discovering the 700+ functions in the Clojure API can take a little longer.  I recommend you find someone with a bit of Clojure experience to guide you.</p> <p>Here is my suggested path to learning Clojure and thinking functionally.  Many of the tasks can be done in parallel.</p>"},{"location":"introduction/learning-clojure/#simple-rather-than-complex-the-foundation-of-clojure","title":"Simple rather than complex - the foundation of Clojure","text":"<p>Gaining an appreciation that systems should be simple is a crucial step truly understanding Clojure.  So early in your journey into Clojure, spend an hour watching Rich Hickey talk about Simple made Easy - (transcript of talk).</p>"},{"location":"introduction/learning-clojure/#experience-the-clojure-syntax","title":"Experience the Clojure syntax","text":"<p>Take a quick look at the Syntax of Clojure.  The syntax is very small, so this will take about 15 minutes to 1 hour (dependent on your own experiences with coding).  Don't try to remember all the syntax, it will come through practise.</p> <ul> <li>eg. Clojure in 15 minutes</li> </ul>"},{"location":"introduction/learning-clojure/#set-up-an-enjoyable-environment-to-work-in","title":"Set up an enjoyable environment to work in","text":"<p>Find how to use Clojure with your favourite editor or IDE.  Configure this tool so you can easily run a REPL and evaluate some expressions.</p> <ul> <li>repl.it - web based repl you can share / fork</li> <li>Spacemacs - for the ultimate Emacs &amp; Vim experience</li> <li>IntelliJ and Cursive</li> <li>Leiningen &amp; any editor you like</li> </ul>"},{"location":"introduction/learning-clojure/#building-a-frame-of-reference-for-functional-programming","title":"Building a frame of reference for functional programming","text":"<p>Find an introductory book that you like which provides lots of example code to help you feel more comfortable with the syntax and more importantly the major concepts of functional programming with Clojure.  Type in the exercises as you read and don't be afraid to play around with code examples</p> <ul> <li>Clojure for the Brave and the True</li> <li>Living Clojure - includes a training guide</li> <li>Practicalli Clojure - you are already here :)</li> <li>ClojureBridge London workshop - aimed at those new to coding</li> <li>PurelyFunctional - Introduction to Clojure</li> </ul>"},{"location":"introduction/learning-clojure/#practice-clojure-standard-library-clojurecore","title":"Practice Clojure standard library (clojure.core)","text":"<p>Practice Clojure.  Write lots of small and relatively simple examples in Clojure and experiment with the code in the REPL and try break things.  This will start helping you learn the Clojure API</p> <p>You should become comfortable in your understanding of:</p> <ul> <li>basic values (strings, numbers, etc) and persistent collections (list, vector, map, set)</li> <li>binding names to values and their scope  (def, defn, let)</li> <li>calling functions, defining functions, arity options for functions</li> <li>Higher order functions and basics of functional composition (map, reduce, filter, etc)</li> <li>Designing with data, Extensible Data Notation (EDN), data manipulation</li> </ul> <p>Activities to help practice Clojure include:</p> <ul> <li>4Clojure.org - aim to complete the first 50 exercises, the first 10 are relatively easy</li> <li>Coding Kata exercises</li> <li>Awesome Kata collection</li> <li>Alice In Wonderland inspired Katas</li> <li>Attend coding dojo events - e.g. London Clojurians</li> </ul>"},{"location":"introduction/learning-clojure/#solidify-some-of-the-basics-you-have-learned-so-far","title":"Solidify some of the basics you have learned so far","text":"<p>Work on a relatively small project that you care about enough to work on</p> <ul> <li>eg. a tool to help you at work</li> </ul>"},{"location":"introduction/learning-clojure/#learn-more-tools-to-help-you-think-functionally","title":"Learn more tools to help you think functionally","text":"<ul> <li>mostly using immutable values and pure functions</li> <li>functional composition, sequences and transducers</li> <li>atoms for managing mutable state changes (with immutable values)</li> </ul>"},{"location":"introduction/learning-clojure/#get-a-broader-view-of-clojure-and-learn-some-common-practices","title":"Get a broader view of Clojure and learn some common practices","text":"<p>Start reading a book which is aimed at intermediate</p> <ul> <li>Clojure CookBook</li> </ul> <p>Watch Video's about Clojure on subjects that are relevant to work or projects you want to work on.</p> <ul> <li>ClojureTV on YouTube</li> </ul> <p>Follow tutorials on Clojure, especially those that introduce the amazing libraries available in Clojure</p> <ul> <li>Lambda Island</li> <li>PurelyFunctional.tv</li> <li>Practical.li</li> </ul> <p>Work with some of the most common libraries in Clojure</p> <ul> <li>Ring / Compojure for web development (server side)</li> <li>ClojureScript for web UI or native mobile apps (client side)</li> <li>Reagent - reactjs style single page apps<ul> <li>Reagent deep dive - excellent tutorial</li> </ul> </li> <li>core.async - for asynchronous programming</li> <li>clojure.string - specific functions for string manipulation</li> <li>tools.logging</li> <li>java.jdbc - database access</li> <li>data.zip - manipulating trees of data, e.g. XML</li> </ul>"},{"location":"introduction/repl-workflow/","title":"REPL Driven Development","text":"<p>Always be REPL'ing</p> <p>Coding without a REPL feels limiting. The REPL provides fast feedback from code as its crafted, testing assumptions and design choices every step of the journey to a solution  - John Stevenson, Practical.li</p> <p>Clojure is a powerful, fun and highly productive language for developing applications and services.  The clear language design is supported by a powerful development environment known as the REPL (read, evaluate, print, loop).  The REPL gives you instant feedback on what your code does and enables you to test either a single expression or run the whole application (including tests).</p> <p>REPL driven development is the foundation of working with Clojure effectively</p> <p>An effective Clojure workflow begins by running a REPL process.  Clojure expressions are written and evaluated immediately to provide instant feedback. The REPL feedback helps test the assumptions that are driving the design choices.</p> <ul> <li>Read - code is read by the Clojure reader, passing any macros to the macro reader which converts those macros into Clojure code.</li> <li>Evaluate - code is compiled into the host language (e.g. Java bytecode) and executed</li> <li>Print - results of the code are displayed, either in the REPL or as part of the application.</li> <li>Loop - the REPL is a continuous process that evaluates code, either a single expression or the whole application.</li> </ul> <p>Design decisions and valuable data from REPL experiments can be codified as specifications and unit tests</p> <p>Practicalli REPL Reloaded Workflow</p> <p>The principles of REPL driven development are implemented in practice using the Practicalli REPL Reloaded Workflow and supporting tooling.  This workflow uses Portal to inspect all evaluation results and log events, hot-load libraries into the running REPL process and reloads namespaces to support major refactor changes.</p>"},{"location":"introduction/repl-workflow/#evaluating-source-code","title":"Evaluating source code","text":"<p>A REPL connected editor is the primary tool for evaluating Clojure code from source code files, displaying the results inline.</p> <p>Source code is automatically evaluated in its respective namespace, removing the need to change namespaces in the REPL with (<code>in-ns</code>) or use fully qualified names to call functions.</p> <p> </p> Evaluate Clojure in a Terminal UI REPL <p>Entering expressions at the REPL prompt evaluates the expression immediately, returning the result directly underneath  </p>"},{"location":"introduction/repl-workflow/#rich-comment-blocks-living-documentation","title":"Rich Comment blocks - living documentation","text":"<p>The <code>(comment ,,,)</code> function wraps code that is only run directly by the developer using a Clojure aware editor.</p> <p>Expressions in rich comment blocks can represent how to use the functions that make up the namespace API.  For example, starting/restarting the system, updating the database, etc.  Expressions provide examples of calling functions with typical arguments and make a project more accessible and easier to work with.</p> <p>Clojure Rich Comment to manage a service</p> <pre><code>(ns practicalli.gameboard.service)\n\n(defn app-server-start [port] ,,,)\n(defn app-server-start [] ,,,)\n(defn app-server-restart [] ,,,)\n\n(defn -main\n  \"Start the service using system components\"\n  [&amp; options] ,,,)\n\n(comment\n  (-main)\n  (app-server-start 8888)\n  (app-server-stop)\n  (app-server-restart 8888)\n\n  (System/getenv \"PORT\")\n  (def environment (System/getenv))\n  (def system-properties (System/getProperties))\n  ) ; End of rich comment block\n</code></pre> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n  (defn value-added-tax []\n    ;; algorithm design - first idea)\n\n  (defn value-added-tax []\n    ;; algorithm design - second idea)\n\n  ) ;; End of rich comment block\n</code></pre> <p>The \"Rich\" in the name is an honourary mention to Rich Hickey, the author and benevolent dictator of Clojure design.</p>"},{"location":"introduction/repl-workflow/#design-journal","title":"Design Journal","text":"<p>A journal of design decisions makes the code easier to understand and maintain.  Code examples of design decisions and alternative design discussions are captured, reducing the time spent revisiting those discussions.</p> <p>Journals simplify the developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A Design Journal is usually created in a separate namespace, although it may start as a rich comment at the bottom of a namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Example design journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"introduction/repl-workflow/#viewing-data-structures","title":"Viewing data structures","text":"<p>Pretty print shows the structure of results from function calls in a human-friendly form, making it easier for a developer to parse and more likely to notice incorrect results.</p> <p>Tools to view and navigate code</p> <ul> <li> Cider inspector is an effective way to navigate nested data and page through large data sets.</li> <li> Portal Inspector to visualise many kinds of data in many different forms.</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#code-style-and-idiomatic-clojure","title":"Code Style and idiomatic Clojure","text":"<p>Clojure aware editors should automatically apply formatting that follows the  Clojure Style guide.</p> <p>Live linting with clj-kondo suggests common idioms and highlights a wide range of syntax errors as code is written, minimizing bugs and therefore speeding up the development process.</p> <p> </p> <p>Clojure LSP is build on top of clj-kondo</p> <p> Clojure LSP uses clj-kondo static analysis to provide a standard set of development tools (format, refactor, auto-complete, syntax highlighting, syntax &amp; idiom warnings, code navigation, etc).</p> <p>Clojure LSP can be used with any Clojure aware editor that provides an LSP client, e.g.  Spacemacs,  Doom Emacs,  Neovim, VSCode.</p> <p>Clojure Style Guide</p> <p>The  Clojure Style guide provides examples of common formatting approaches, although the development team should decide which of these to adopt.  Emacs <code>clojure-mode</code> will automatically format code and so will Clojure LSP (via cljfmt).  These tools are configurable and should be tailored to the teams standard.</p>"},{"location":"introduction/repl-workflow/#data-and-function-specifications","title":"Data and Function specifications","text":"<p> Clojure spec is used to define a contract on incoming and outgoing data, to ensure it is of the correct form.</p> <p>As data structures are identified in REPL experiments, create data specification to validate the keys and value types of that data.</p> <pre><code>;; ---------------------------------------------------\n;; Address specifications\n(spec/def ::house-number string?)\n(spec/def ::street string?)\n(spec/def ::postal-code string?)\n(spec/def ::city string?)\n(spec/def ::country string?)\n(spec/def ::additional string?)\n\n(spec/def ::address   ; Composite data specification\n  (spec/keys\n   :req-un [::street ::postal-code ::city ::country]\n   :opt-un [::house-number ::additional]))\n;; ---------------------------------------------------\n</code></pre> <p>As the public API is designed, specifications for each functions arguments are added to validate the correct data is used when calling those functions.</p> <p> Generative testing provides a far greater scope of test values used incorporated into unit tests. Data uses clojure.spec to randomly generate data for testing on each test run.</p>"},{"location":"introduction/repl-workflow/#test-driven-development-and-repl-driven-development","title":"Test Driven Development and REPL Driven Development","text":"<p>Test Driven Development (TDD) and REPL Driven Development (RDD) complement each other as they both encourage incremental changes and continuous feedback.</p> <p>Test Driven Development fits well with Hammock Time, as good design comes from deep thought</p> <ul> <li>RDD enables rapid design experiments so different approaches can easily and quickly be evaluated .</li> <li>TDD focuses the results of the REPL experiments into design decisions, codified as unit tests.  These tests guide the correctness of specific implementations and provide critical feedback when changes break that design.</li> </ul> <p> Unit tests should support the public API of each namespace in a project to help prevent regressions in the code.  Its far more efficient in terms of thinking time to define unit tests as the design starts to stabilize than as an after thought.</p> <p><code>clojure.test</code> library is part of the Clojure standard library that provides a simple way to start writing unit tests.</p> <p> Clojure spec can also be used for generative testing, providing far greater scope in values used when running unit tests.  Specifications can be defined for values and functions.</p> <p>Clojure has a number of  test runners available.  Kaocha is a test runner that will run unit tests and function specification checks.</p> <p>Automate local test runner</p> <p>Use  kaocha test runner in watch mode to run tests and specification check automatically (when changes are saved) <pre><code>clojure -X:test/watch\n</code></pre></p>"},{"location":"introduction/repl-workflow/#continuous-integration-and-deployment","title":"Continuous Integration and Deployment","text":"<p>Add a  continuous integration service to run tests and builds code on every shared commit.  Spin up testable review deployments when commits pushed to a pull request branch, before pushing commits to the main deployment branch, creating an effective pipeline to gain further feedback.</p> <ul> <li> CircleCI provides a simple to use service that supports Clojure projects.</li> <li> GitHub Workflows and GitHub actions marketplace to quickly build a tailored continuous integration service, e.g. Setup Clojure GitHub Action.</li> <li> GitLab CI</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#live-coding-with-data-stuart-halloway","title":"Live Coding with Data - Stuart Halloway","text":"<p>There are few novel features of programming languages, but each combination has different properties. The combination of dynamic, hosted, functional and extended Lisp in Clojure gives developers the tools for making effective programs. The ways in which Clojure's unique combination of features can yield a highly effective development process.</p> <p>Over more than a decade we have developed an effective approach to writing code in Clojure whose power comes from composing many of its key features. As different as Clojure programs are from e.g. Java programs, so to can and should be the development experience. You are not in Kansas anymore!</p> <p>This talk presents a demonstration of the leverage you can get when writing programs in Clojure, with examples, based on my experiences as a core developer of Clojure and Datomic.</p> <p> </p>"},{"location":"introduction/who-uses-clojure/","title":"Who uses Clojure","text":"<p>Hundreds of companies actively advertised their Clojure adoption. Given the broad participation in user groups there are clearly many more organizations using Clojure at some level in their technology stack.</p> <p>A quick scan of various job sites shows Clojure positions at companies like Walmart, Facebook, Staples, Consumer Reports, Salesforce, and Amazon. It doesn't get much more mainstream than that.</p> <p>If you are looking for a new role using Clojure or other functional programming languages, visit Functional Works, the only Functional Recruiters in the world.</p> <p>Here is just a small and diverse set of example companies that I am aware of that use Clojure for development.</p> Company Type of applications Boeing Boeing 737 MAX - onboard maintenance Puppet Labs DevOps apps &amp; services e.g. trapperkeeper Cisco Malware analysis &amp; threat intelligence platform (expert system with core.logic) Deuche Bank (UK) Processing event streams from Apache Storm Atlassian Collaborative editing platform for all their products Netflix Map-Reduce languages for writing apps for Hadoop / Pig USwitch (UK) Creating meaningful data from multiple sources Daily Mail Online (UK) Publishing pipeline Circle CI (USA) Front-end of CI server in ClojureScript &amp; test suite CitiGroup Financial Trading Student Loans company (UK) Loans management system written in Clojure LinkedIn Powers the LinkedIn social graph Walmart (USA) eReceipts project to process every purchase from 5,000+ stores SwiftKey (UK) Predictive intelligence platform (possibly used with Microsoft Cortana) Roomkey.co.uk Hotel booking system to rival Expedia (with a tiny development team) Funding Circle (UK &amp; USA) Adopting Clojure as their main language (from Ruby, etc) Braintree Payment processing pipeline with Kafka Mastodon C Data centre analysis (Incanta, Storm) Thoughtworks Agile development for Client projects world wide Vero Insurance (AUS) Rebuilt policy management system in Clojure with Thoughworks Meta-X Performance art (Overtone, Quil) Salesforce (USA) Build &amp; deployment with Puppet &amp; Application Routing with nginx-clojure <p>There are many more examples of projects on the HackerNews thread: Ask HN: Who's using Clojure in Production</p>"},{"location":"introduction/who-uses-clojure/#tech-radar","title":"Tech Radar","text":"<p>Clojure is also defined as a technology that can be adopted since 2014, according to the Thoughtworks technology radar.</p> <p></p> <p>JUXT also created its own Clojure specific technology radar as there is such an encompassing ecosystem of libraries and services.</p>"},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"<p>Making the docs more engaging using the mkdocs-material theme reference guide</p> Configuring Colors <p>Material for MkDocs - Changing the colors lists the primary and accent colors available.</p> <p>HSL Color Picker for codes to modify the theme style, overriding colors in <code>docs/assets/stylesheets/extra.css</code></p>"},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"<p>Links open in the same browser window/tab by default.</p> <p>Add <code>{target=_blank}</code> to the end of a link to configure opening in a new tab</p> <pre><code>[link text](url){target=_blank}\n</code></pre>"},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"<p>Convert any link into a button by adding <code>{.md-button}</code> class names to end of the markdown for a link, which uses <code>.md-button-primary</code> by default.  Include <code>target=_blank</code> for buttons with links to external sites.</p> <pre><code>[link text](http://practical.li/blog){.md-button target=_blank}\n</code></pre> <p>Or specify a different class</p> <pre><code>[link text](http://practical.li/blog){.md-button .md-button-primary}\n</code></pre> <p>Add an icon to the button</p> <p> Practicalli Issues  Practicalli Blog</p> <pre><code>[:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n</code></pre> <p>Search all supported icons</p>"},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"<p>Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position</p> <pre><code>&lt;p style=\"text-align:center\"&gt;\n&lt;iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen&gt;&lt;/iframe&gt;\n&lt;/p&gt;\n</code></pre> <p>mkdocs material does not have direct support for adding a YouTube video via markdown.</p>"},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"<p>Supported admonition types</p> <p>Note</p> <p>Use <code>!!!</code> followed by <code>NOTE</code></p> <p>Adding a title</p> <p>Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> <p>Shh, no title bar just the text... Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"\"</code> empty double quotes</p> <p>Abstract</p> <p>Use <code>!!!</code> followed by <code>ABSTRACT</code></p> <p>Info</p> <p>Use <code>!!!</code> followed by <code>INFO</code></p> <p>Tip</p> <p>Use <code>!!!</code> followed by <code>TIP</code></p> <p>Success</p> <p>Use <code>!!!</code> followed by <code>SUCCESS</code></p> <p>Question</p> <p>Use <code>!!!</code> followed by <code>QUESTION</code></p> <p>Warning</p> <p>Use <code>!!!</code> followed by <code>WARNING</code></p> <p>Failure</p> <p>Use <code>!!!</code> followed by <code>FAILURE</code></p> <p>Danger</p> <p>Use <code>!!!</code> followed by <code>DANGER</code></p> <p>Bug</p> <p>Use <code>!!!</code> followed by <code>BUG</code></p> <p>Example</p> <p>Use <code>!!!</code> followed by <code>EXAMPLE</code></p> <p>Quote</p> <p>Use <code>!!!</code> followed by <code>QUOTE</code></p>"},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note <p>Collapse those admonitions using <code>???</code> instead of <code>!!!</code></p> Replace with a title <p>Use <code>???</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> Expanded by default <p>Use <code>???+</code>, note the <code>+</code> character,  followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p>"},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"<p>Inline blocks of text to make a very specific callout within text</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Adding something to then end of text is probably my favourite</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"<p>Code blocks include a copy icon automatically</p> <p>Syntax highlighting in code blocks</p> <pre><code>(defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Give the code block a title using <code>title=\"\"</code> after the backtics and language name</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>We all like line numbers, especially when you can set the starting line</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Add <code>linenums=42</code> to start line numbers from 42 onward</p> <pre><code>clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n</code></pre>"},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"<p>Annotations in a code block help to highlight important aspects.  Use the comment character for the language followed by a space and a number in brackets</p> <p>For example, in a shell code block, use <code># (1)</code> where 1 is the number of the annotation</p> <p>Use a number after the code block to add the text for the annotation, e.g. <code>1.</code>. Ensure there is a space between the code block and the annotation text.</p> <pre><code>ls -la $HOME/Downloads  # (1)\n</code></pre> <ol> <li> I'm a code annotation! I can contain <code>code</code>, formatted text, images, ... basically anything that can be written in Markdown.</li> </ol> <p>Code blocks with annotation, add <code>!</code> after the annotation number to suppress the <code>#</code> character</p> <pre><code>(defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n</code></pre> <ol> <li>Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.</li> </ol> <p>GitHub action example with multiple annotations</p> <pre><code>name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n</code></pre> <ol> <li> <p>You can change the name to your liking.</p> </li> <li> <p>At some point, GitHub renamed <code>master</code> to <code>main</code>. If your default branch     is named <code>master</code>, you can safely remove <code>main</code>, vice versa.</p> </li> <li> <p>This is the place to install further [MkDocs plugins] or Markdown     extensions with <code>pip</code> to be used during the build:</p> <pre><code>pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n</code></pre> </li> </ol>"},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"<p>Add highlight line meta data to a code block after the opening backticks and code block language.</p> <p><code>hl_lines=\"2\"</code> highlights line 2 in the codeblock</p> <pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n</code></pre>"},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"<p><code>--8&lt;--</code> in a code block inserts code from a source code file or other text file</p> <p>Specify a local file from the root of the book project (the directory containing mkdocs.yml)</p> Scheduled Version Check GitHub Workflow from source code file scheduled version check<pre><code>\n</code></pre> Practicalli Project Templates Emacs project configuration - .dir-locals.el<pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n</code></pre> <p>Code example reuse</p> <p>Use an embedded local or external file (URL) when the same content is required in more than one place in the book.</p> <p>An effective way of sharing code and configuration mutliple times in a book or across multiple books.</p>"},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"<p>Create in page tabs that can also be</p> <p>Setting up a project</p> Clojure CLILeiningen <pre><code>clojure -T:project/new :template app :name practicalli/gameboard\n</code></pre> <pre><code>lein new app practicalli/gameboard\n</code></pre> <p>Or nest the content tabs in an admonition</p> <p>Run a terminal REPL</p> Clojure CLILeiningen <pre><code>clojure -T:repl/rebel\n</code></pre> <pre><code>lein repl\n</code></pre>"},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"<p>Neat flow diagrams</p> <p>Diagrams - Material for MkDocs</p> <pre><code>graph LR\n  A[Start] --&gt; B{Error?};\n  B --&gt;|Yes| C[Hmm...];\n  C --&gt; D[Debug];\n  D --&gt; B;\n  B ----&gt;|No| E[Yay!];</code></pre> <p>UML Sequence Diagrams</p> <pre><code>sequenceDiagram\n  Alice-&gt;&gt;John: Hello John, how are you?\n  loop Healthcheck\n      John-&gt;&gt;John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John--&gt;&gt;Alice: Great!\n  John-&gt;&gt;Bob: How about you?\n  Bob--&gt;&gt;John: Jolly good!</code></pre> <p>state transition diagrams</p> <pre><code>stateDiagram-v2\n  state fork_state &lt;&lt;fork&gt;&gt;\n    [*] --&gt; fork_state\n    fork_state --&gt; State2\n    fork_state --&gt; State3\n\n    state join_state &lt;&lt;join&gt;&gt;\n    State2 --&gt; join_state\n    State3 --&gt; join_state\n    join_state --&gt; State4\n    State4 --&gt; [*]</code></pre> <p>Class diagrams - not needed for Clojure</p> <p>Entity relationship diagrams are handy though</p> <pre><code>erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses</code></pre>"},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"<p>Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.</p> <ul> <li>1 <code>++1++</code> for numbers</li> <li>l <code>++\"l\"++</code> for lowercase character</li> <li>U <code>++u++</code> for uppercase character or <code>++\"U\"++</code> for consistency</li> </ul> <p>Punctionation keys use their name</p> <ul> <li>Space <code>++spc++</code></li> <li>, <code>++comma++</code></li> <li>Left <code>++arrow-left++</code></li> </ul> <p>For key sequences, place a space between each keyboard character</p> <ul> <li>Space g s <code>++spc++ ++\"g\"++ ++\"s\"++</code></li> </ul> <p>For key combinations, use join they key identifies with a <code>+</code></p> <ul> <li>Meta+X <code>++meta+x++</code></li> <li>Ctrl+Alt+Del <code>++ctrl+alt+del++</code></li> </ul> <p>MkDocs keyboard keys reference</p>"},{"location":"introduction/writing-tips/#images","title":"Images","text":"<p>Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers</p> SizeLazy LoadingAlignTheme SpecificAll Image Attributes <p><code>{style=\"height:150px;width:150px\"}</code> specifies the image size <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n</code></pre></p> <p></p> <p><code>{loading=lazy}</code> specifies an image should lazily load in the browser <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n</code></pre></p> <p><code>{aligh=left}</code> or <code>{aligh=right}</code> specifies the page alignment of an image. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n</code></pre></p> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p><code>![Kitty Logo](image/kitty-light.png#only-dark)</code> or <code>![Kitty Logo](image/kitty-light.png#only-light)</code>  specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n</code></pre> Use the theme toggle in the top nav bar to see the icon change between light and dark.  </p> <p>Requires the color pallet toggle</p> <p>Alight right, lazy load and set image to 150x150</p> <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n</code></pre> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"<p>Task lists</p> <ul> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit</li> <li> Vestibulum convallis sit amet nisi a tincidunt<ul> <li> In hac habitasse platea dictumst</li> <li> In scelerisque nibh non dolor mollis congue sed et metus</li> <li> Praesent sed risus massa</li> </ul> </li> <li> Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque</li> </ul> <p>Task List example</p> <pre><code>- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n</code></pre>"},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"<p>The humble tool tip</p> <p>Hover me</p> <p>with references</p> <p>Hover me</p> <p>Icon tool tip with a title</p> <p></p>"},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"<p>The HTML specification is maintained by the W3C.</p> <p>[HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium</p>"},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"<p>MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.</p> <p>Email Practicalli</p> <p>Practicalli Neovim</p>"},{"location":"introduction/concepts/","title":"Clojure concepts","text":"<p>Clojure is an elegant language for a more civilized development experience.</p> <p>Clojure supports the creation of simple software systems using immutable values and encouraging a pragmatic approach to pure functional design.</p> <p>A simple syntax means Clojure is quick to learn and a wide range of open source libraries provides a rapid way to build any kind of software. Designed as a hosted language, Clojure runs on many platforms including the Java Virtual Machine, GraalVM, Microsoft.Net, JavaScript engines.  Simple host language interoperability provides access to libraries from a wide range of programming languages, further extending the reach of Clojure.</p> <p>Experiment with the Clojure language to help understand concepts</p> <p>Spend some time eevaluating code in the REPL and then revisit this section to get a deeper understanding of the design and philosophy of the Clojure approach to functional programming.</p> <p>Clojure concepts are easier to relate to whist practicing with Clojure and building Clojure software solutions.</p>"},{"location":"introduction/concepts/#ten-big-ideas-plus-one","title":"Ten Big Ideas plus one","text":"<p>The key to understanding Clojure is ideas, not language constructs but the concepts that shape the language.</p> <p>Each of these ideas is valuable by itself, not only in Clojure. Taken together, however, they Begin to fill in the picture of why Clojure is changing the way many programmers think about software development.</p> <ol> <li>Extensible Data Notation</li> <li>Persistent Data Structures</li> <li>Sequences</li> <li>Transducers</li> <li>Specification</li> <li>Dynamic Development</li> <li>Async Programming</li> <li>Protocols</li> <li>ClojureScript</li> <li>Logic query / Logic Programming</li> <li>Atomic Succession Model</li> </ol> <p>Stuart Halloway presents Clojure in 10 big ideas (plus one) in the following video, also see presentation Content</p> <p> </p> <ul> <li>2013 RuPy slides</li> <li>2017 Chicago JUG slides</li> </ul>"},{"location":"introduction/concepts/#antithesis-of-clojure-and-simple-software-design","title":"Antithesis of Clojure and simple software design","text":"<p>In Narcissistic Design by Stuart Halloway, the antithesis of the Clojure view of software development is presented as a description of how unproductive and valueless much of the software industry has been in the past.</p> <p>Its essentially a guide on what to avoid if you are a responsible and professional software developer.</p> <p> </p>"},{"location":"introduction/concepts/all-bytecode-in-the-end/","title":"Its all Bytecode in the end","text":"<p>The REPL is your compiler</p> <p></p> <p>As soon as you evaluate your code in the REPL it is also being compiled in the background into Java Bytecode.  So there is no need for a separate build and run phase.</p> <p>Injecting code into the running environment provides the means for fast iterative development of code.</p>"},{"location":"introduction/concepts/clojure-made-simple/","title":"Clojure from the Author","text":"<p>A series of important videos from Rich Hickey, the author of Clojure who spent over 2 years designing core of Clojure around the concept of simplicity.  Since then Rich has stewarded the continued design and development of Clojure, ensuring it stays true to is founding principles.</p> <p>You do not need to watch these videos to start coding in Clojure, but they are very useful to adopt the approach and design idioms that make Clojure a highly effective language for software development.</p>"},{"location":"introduction/concepts/clojure-made-simple/#expert-to-expert-rich-hickey-and-brian-beckman-inside-clojure","title":"Expert to Expert: Rich Hickey and Brian Beckman - Inside Clojure","text":"<p>Discussing some of the key characteristics of the Clojure language and why those decisions were taken</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#clojure-made-simple","title":"Clojure made simple","text":"<p>Covers the major problems with software development and the challenges most programming languages fail to tackle completely.</p> <p>Discusses a simple approach to software development and the big picture view of how Clojure solves these problems</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#simplicity-matters","title":"Simplicity Matters","text":"<p>!!! QUOTE Rich Hickey, Clojure Benevolent Dictator for Life     As we move forward we have to take what we already have and make that [software] do more, make it do things differently, make it do things better,  and as we try to take on manipulating software we are going to be challenged to understand it in order to make that happen.     And I'll contend that you will completely be dominated by complexity.  I don't care what processes you are using, I don't care how well you test or anything else.  Complexity will dominate what you do.</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#discussing-design","title":"Discussing Design","text":""},{"location":"introduction/concepts/clojure-made-simple/#the-value-of-values","title":"The value of values","text":"<p>Rich Hickey provides analysis of the changing way we think about values (not the philosophical kind) in light of the increasing complexity of information technology and the advent of Big Data</p> <p> </p> <p>Also see the related video: Database as a value by Rich Hickey</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#understanding-clojure-as-a-programming-language","title":"Understanding Clojure as a programming language","text":""},{"location":"introduction/concepts/design/","title":"Clojure Design","text":"<p>Clojure leads to a very component based approach to development.  There are no huge and bloated frameworks in Clojure.  The core is very small.  Hundreds of focused libraries to use in collaboration.</p> <p>Boiled down to the most simplest structure, Clojure applications you write typically look like this:</p> <pre><code>;; define a namespace\n(ns name-space.name)\n\n;; define one or more immutable data structures - the fewer the better typically\n(def my-data-structure [[{}{}]])\n\n;; define behaviour that acts on data structures inside one or more functions\n(defn my-function [parameter]\n  (my-behaviour parameter))\n\n;; Call those functions to make your application do something\n(my-behaviour data)\n</code></pre> <p>Hint As functions always evaluate to a value, a function can be used as an argument to another function (or itself if you get recursive !!)</p>"},{"location":"introduction/concepts/design/#data-focused-design-maps-vectors","title":"Data focused design - Maps &amp; Vectors","text":"<p>Maps (hash-map) and vectors are two more built-in persistent data structures that are more commonly used to represent data within a Clojure application.</p> <p>A vector is similar to an array in that its an indexed collection and so has fast random access.  Vectors are a catch all data structure that can hold any type of information, including other data structures and function calls.</p> <p>A hash-map is an associative data structure with key value pairs.  The keys are most commonly represented with Clojure keywords, although keys can be strings, numbers, collections or functions so long as all the keys are unique.</p> <p>Hash-maps are a collection of key / value pairs that provide an easy way to reference data by keys.  Its common to use a Clojure <code>keyword</code> type as the keys as keywords are self-referential (they point to themselves).  Using keywords in a map means you can use a specific keyword as a function call on the map that returns its associated value.</p> <p>Some examples of using these data structures this are:</p> <pre><code>;; A map of maps of maps with occasional vectors\n\n{:star-wars {\n    :characters {\n      :jedi   [\"Luke Skywalker\"\n               \"Obiwan Kenobi\"]\n      :sith   [\"Darth Vader\"\n               \"Darth Sideous\"]\n      :droids [\"C3P0\"\n               \"R2D2\"]}\n    :ships {\n      :rebel-alliance  [\"Millennium Falcon\"\n                        \"X-wing fighter\"]\n      :imperial-empire [\"Intergalactic Cruiser\"\n                        \"Destroyer\"\n                        \"Im just making these up now\"]}}}\n</code></pre>"},{"location":"introduction/concepts/design/#hintbasic-design-principle","title":"Hint::Basic design principle","text":"<p>\u201cIt is better to have 100 functions operate on one data structure than 10 functions on 10 data structures.\u201d \u2014Alan Perlis</p>"},{"location":"introduction/concepts/design/#extensibility-via-macros","title":"Extensibility via Macros","text":"<p>You can extend the language and define your own constructs using Macros.</p> <p>The first example of this you see is from Leiningen.  The <code>defproject</code> function is a macro that helps you easily define the configuration of a Clojure project.</p> <p>An example of a macro that is part of the core Clojure language is <code>defn</code>.  When you define a function with <code>defn</code> it is syntactic sugar for defining a thing that is a function.</p> <pre><code>  (defn my-function [argument] (my-behaviour argument) )\n\n  (def my-function\n    (fn [argument] (my-behaviour argument)))\n</code></pre>"},{"location":"introduction/concepts/design/#special-forms-the-building-blocks-of-clojure","title":"Special forms - the building blocks of Clojure","text":"<p>The following are the building blocks of Clojure, everything else is either a macro or a function</p> <p>The Clojure / LISP special forms</p> <pre><code>def, do, if, let, loop, fn, quote, recur, set!, var\n</code></pre> <p>The forms added for Interoperability with the host platform (mainly Java / JVM)</p> <pre><code>monitor-enter, monitor-exit,\ncatch, dot ('.'), finally, new, throw, try\n</code></pre>"},{"location":"introduction/concepts/features/","title":"Features of Clojure","text":""},{"location":"introduction/concepts/features/#dynamic-language","title":"Dynamic language","text":"<p>A problem space can quickly be explored through code to test your assumptions.  The design of code is easy to change as you are not managing type changes, Clojure is very good at managing data that would otherwise lead to exceptions.</p> <p>As a dynamic language the code is quite terse and developers are encouraged to write very modular code, therefore it is easy to refactor.</p>"},{"location":"introduction/concepts/features/#dynamic-development-repl","title":"Dynamic Development - REPL","text":"<p>Clojure has a REPL (Read Evaluate Print Loop), this is the Clojure run-time environment.  You can define functions and data structures, then evaluate them to run either all your code or just a single expression.  You can even change code and re-evaluate it whilst your application is still running and immediately see the effect that change has.</p> <p>So the REPL is a very fast way to explore your problem domain with code</p> <p>You could even connect to the REPL of a live system and change its behaviour without any down time (unless of course you write code that crashes).</p>"},{"location":"introduction/concepts/features/#pure-functional-programming","title":"'Pure' Functional Programming","text":"<p>Functions return a value (even if that value is nil) and you can therefore use a function as an argument to another function.  This is termed as first order functions.</p> <p>Clojure encourages a relatively pure approach to functional programming and Clojure can be considered immutable by default</p>"},{"location":"introduction/concepts/features/#immutability","title":"Immutability","text":"<ul> <li>immutable data structures at its core, everything is immutable by default</li> <li>in imperative programming, we change state where ever we like</li> <li>in functional programming we avoid changing state as much as possible</li> <li>if a function does not change state it is referentially transparent, always returning the same result when given the same input (arguments) - often returned as a pure function</li> <li>impure functions can affect other functions and therefore has to be very mindful of the changes it makes and when it makes them</li> <li>pure functions are truly modular as they do not affect any other part of the system</li> </ul>"},{"location":"introduction/concepts/features/#persistent-data-structures","title":"Persistent Data Structures","text":"<p>List, Map, Vector and Set are all built in data structures that are immutable.</p> <p>If you run a function that seems to change a data structure, its actually returning a new data structure.  Via a shared-memory model, new data structures are created cheaply as they share the common data elements from the original data structure and only include additional elements.</p>"},{"location":"introduction/concepts/features/#homoiconicity","title":"Homoiconicity","text":"<p>One thing that keeps Clojure a small language is the fact that the same syntax is used to represent data and behaviour.  For example, a function call is defined using a list, data structures and functions are defined using a list.  In fact everything is a list, although we use a little syntactic sugar here and there to make the code quicker for a human to parse.</p>"},{"location":"introduction/concepts/features/#clojure-is-an-implementation-of-lisp","title":"Clojure is an implementation of Lisp","text":"<p>Lisp stands for LISt Processing, so its no surprise that all Clojure code is defined in a list.</p> <p>The open Parenthesis <code>(</code> denotes the start of a list, the first element of that list is evaluated as a function call, everything else in the list is data.</p> <p>The evaluation of the first element of a list can be behaviour of <code>(</code> can be over-ridden using <code>quote</code> or its short form the quote character, ', so the list elements are all treated as data.</p>"},{"location":"introduction/concepts/features/#runtime-polymorphism","title":"Runtime Polymorphism","text":"<p>See Clojure arity and multi-methods for more information</p>"},{"location":"introduction/concepts/features/#concurrent-programming-parallelism","title":"Concurrent Programming &amp; Parallelism","text":"<p>Concurrent code is much safer when you data does not change state (eg. immutable values).  Clojure encourages an immutable approach with its built in persistent data structures (list, Map, Vector, Set).  Using Pure Functions that are not affected by or cause side effects also make writing concurrent code trivial.</p> <p>Clojure helps you scale your applications by with a parallel processing approach, as you can run functions over immutable data-structures without conflict.</p>"},{"location":"introduction/concepts/features/#hosted-on-the-jvm","title":"Hosted on the JVM","text":"<p>Clojure is compiled to bytecode that runs on the Java Virtual Machine.  This helps Clojure run at a very high performance (close to Java, C++, etc.)</p> <p>Clojure has a concise and easy to use Java Interoperability, enabling you to use any libraries that run on the JVM (Java, Groovy, Scala, Jruby, Jython, etc).</p> <ul> <li>many parts of the Clojure standard library, Clojure.core defer to the Java Standard library, for example for I/O (reading,writing files)</li> <li>Clojure makes invoking Java very convenient and provides special primitive constructs in the Clojure language to do so (new .javaMethodName javaClassName. etc)</li> </ul> <p>ClojureScript generated JavaScript that will run in a browser.  ClojureCLR will compile to bytecode that runs on the Microsoft .Net platform.</p>"},{"location":"introduction/concepts/features/#managed-state-changes","title":"Managed State Changes","text":"<p>Using <code>atoms</code> or <code>refs</code> in clojure you can have mutable data.  Changes are done safely within Software Transactional Memory (STM), like having an in-memory ACID database managing access</p>"},{"location":"introduction/concepts/features/#extend-the-language-with-macros","title":"Extend the language with Macros","text":"<p>Clojure uses macros</p> <p>Fixme Review the following content to see if its relevant ?</p> <p>** Input &amp; output with functional programming</p> <ul> <li>other fp languages like haskel &amp; Scala use monads to encapsulate data changes whilst appearing stateless to the rest of the program - monads allow us to sneak in impure code into the context of pure code.</li> <li>Clojure doesn't try and enforce functional purity, so any function can include impure code</li> <li>most functions should be pure though or you loose the benefits of functional programming</li> <li>Clojure encourages minimal state changes / mutable state - so its up to the developer to keep the ratio of mutable data small</li> <li> <p>Clojure uses reference types to manage threads and mutable state.  References provide synchronisation of threads without using locks (notoriously cumbersome).  See STM</p> </li> <li> <p>Supporting concurrency</p> </li> <li> <p>atoms etc</p> </li> <li>automatic management of state changes via Software transactional memory - like having an ACID database in memory, managing requests to change values over time.</li> <li> <p>by having immutable data structures - if your values do not change then its trivial to have massive parallelism.</p> </li> <li> <p>A modern LISP</p> </li> <li> <p>leaner syntax and not as many brackets as LISP</p> </li> <li>clean data structure syntax at the core of the language</li> <li>LiSP was the first language to introduce first class functions, garbage collection and dynamic typing, which are common in languages used today</li> </ul> <p>Macros</p> <ul> <li>a function that takes in source code and returns source code, replacing the macro code</li> <li>use macros to take out repetition / boilerplate code</li> <li>as LISP syntax is extremely simple it is much easier to write macros that work compared to non-LISP languages</li> </ul> <p>Clojure emphasizes safety in its type system and approach to parallelism, making it easier to write correct multi-threaded programs.</p> <p>Clojure is very concise, requiring very little code to express complex operations.</p> <p>Data centric design - a well constructed data structure helps define and clarify the purpose of the code</p> <p>Modularity - Clojure and its community build things in modules / components that work together (in a similar design approach to the Unix file system, for example).</p> <p>It offers a REPL and dynamic type system: ideal for beginners to experiment with, and well-suited for manipulating complex data structures.</p> <p>A consistently designed standard library and full-featured set of core data types rounds out the Clojure toolbox.</p> <p>Clojure is close to the speed of Java</p>"},{"location":"introduction/concepts/features/#constraints","title":"Constraints","text":"<p>Clojure relies on the JVM so there can be a longer boot time than a scripting language like Javascript.  However, as you can connect to the Clojure runtime (the REPL) of a live system and because Clojure is dynamic, you can make changes to that live system without any downtime.</p> <p>If you require more performance from Clojure, you can specify ahead of time compilation.</p>"},{"location":"introduction/concepts/functional-reactive-programming/","title":"Functional Reactive Programming","text":"<p>Functional Reactive programming is used in ClojureScript with libraries including reagent, re-frame, rum, etc.</p> <p>Functional Reactive Programming is an elegant means of modeling state over time in an easily composable way. Approaching the problem conceptually and developing a formal semantics first can lead to better optimization potential and simpler implementation.</p> <p>Taking a functional reactive programming approach results in systems that are:</p> <ul> <li>Easier to reason about</li> <li>Simpler to implement</li> <li>Easier to optimize</li> </ul> <p>Functional Reactive Programming (FRP) is a specific formalism of a model of behaviors that change in response to events, created by Conal Elliot. That's a pretty abstract statement, but FRP is abstract itself. It does not denote a particular implementation, but rather a formal semantics. It is not a style of programming or a paradigm. It's simply a formalism.</p> <p>Functional Reactive Programming (and Denotational Design, also by Conal Elliott) has a lot to teach us about how to design functional programs.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#conal-elliott-on-frp-audio-interview","title":"Conal Elliott on FRP Audio Interview","text":"<p>If you're looking for an explanation of the Functional Reactive Programming from the man who invented it, along with an idea of the intriguing process he used to invent it, this HaskellCast episode is for you.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#functional-reactive-animation","title":"Functional Reactive Animation","text":"<p>A great paper from 1997 that spells out an early form of Functional Reactive Programming. It specifies behaviors (functions of time to a value) that change when events occur.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#conal-elliots-home-page","title":"Conal Elliot's home page","text":"<p>Conal Elliot created FRP while he was researching graphics and animation. Be sure to check out his FRP papers section.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#push-pull-functional-reactive-programming","title":"Push-pull functional reactive programming","text":"<p>A more advanced formulation of Functional Reactive Programming that formalizes the types and operations using Haskell's common type classes (Functor, ApplicativeFunctor, Monoid, etc). This one also includes a video of the paper presentation given at ICFP.</p> <p>The main breakthrough of this paper is to model the notion of a future value for events that have not yet happened. But if they have not happened, how can future values be compared? For instance, how does one ask if event a happens before event b if neither of them has happened yet? The paper develops a cool and inspiring formalism which resolves this problem. And one is left with a value that represents the entire behavior of a system past, present, and future.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#elm-thesis-pdf","title":"Elm Thesis - PDF","text":"<p>Elm is a different take on FRP (and it is potentially not FRP, according to some). Instead of behaviors (functions of time to a value), Elm uses discreet signals which are transformed to other signals using functional map-like operations. It also solves a real issue with computationally expensive operations blocking the propagation of signals by making some signals asynchronous.</p> <p>All-in-all, the thesis is a pleasure to read. It is very clear and a decent introduction to the myriad implementations of FRP out there. See the bibliography.</p>"},{"location":"introduction/concepts/misc/","title":"Misc","text":""},{"location":"introduction/concepts/misc/#characteristics","title":"Characteristics","text":"<ul> <li>Dynamic</li> <li>typed - like Python, Ruby or Groovy</li> <li>because its a LISP - you can redefine running code by redefining functions and re-evaluating</li> <li> <p>REPL - a fast way to explore your problem domain with code</p> </li> <li> <p>Functional programming</p> </li> <li>in contrast to imperative programing</li> <li>immutable data structures at its core, everything is immutable by default</li> <li>if any piece of data can be changed, that is mutable state</li> <li>in imperative programming, we change state where ever we like</li> <li>in functional programming we avoid changing state as much as possible</li> <li>if a function does not change state it is referentially transparent, always returning the same result when given the same input (arguments) - often returned as a pure function</li> <li>impure functions can affect other functions and therefore has to be very mindful of the changes it makes and when it makes them</li> <li>pure functions are truly modular as they do not affect any other part of the system ** Changing state</li> <li>rather than changing a data structure, fp instead creates a new data structure that contains the changes and copies of the existing data.</li> <li>to manage the potential overhead of copying data structures, Clojure uses Persistent collections (Lists, Vectors, Maps) which are immutable but provide an efficient way to mutate by sharing common elements (data) ** Input &amp; output with functional programming</li> <li>other fp languages like haskel &amp; Scala use monads to encapsulate data changes whilst appearing stateless to the rest of the program - monads allow us to sneak in impure code into the context of pure code.</li> <li>Clojure doesn't try and enforce functional purity, so any function can include impure code</li> <li>most functions should be pure though or you loose the benefits of functional programming</li> <li>Clojure encourages minimal state changes / mutable state - so its up to the developer to keep the ratio of mutable data small</li> <li> <p>Clojure uses reference types to manage threads and mutable state.  References provide synchronisation of threads without using locks (notoriously cumbersome).  See STM</p> </li> <li> <p>Hosted on the Java Virtual Machine</p> </li> <li>written for the JVM &amp; heavily integrated, giving beautiful integration</li> <li>Clojure is compiled to Java byte code</li> <li>many parts of the Clojure standard library, Clojure.core defer to the Java Standard library, for example for I/O (reading,writing files)</li> <li> <p>Clojure makes invoking Java very convenient and provides special primitive constructs in the Clojure language to do so (new .javaMethodName javaClassName. etc)</p> </li> <li> <p>Supporting concurrency</p> </li> <li>atoms etc</li> <li>automatic management of state changes via Software transactional memory - like having an ACID database in memory, managing requests to change values over time.</li> <li> <p>by having immutable data structures - if your values do not change then its trivial to have massive parallelism.</p> </li> <li> <p>A modern LISP</p> </li> <li>leaner syntax and not as many brackets as LISP</li> <li>clean data structure syntax at the core of the language</li> <li>LiSP was the first language to introduce first class functions, garbage collection and dynamic typing, which are common in languages used today</li> </ul> <p>Macros</p> <ul> <li>a function that takes in source code and returns source code, replacing the macro code</li> <li>use macros to take out repetition / boilerplate code</li> <li>as LISP syntax is extremely simple it is much easier to write macros that work compared to non-LISP languages</li> </ul> <p>fixme assuming you need more, I'll add to this page, but Clojure is a very powerful language, incredibly flexible and tonnes of fun.  What more do you need ?</p> <p>fixme concepts to explore</p> <p>Clojure emphasizes safety in its type system and approach to parallelism, making it easier to write correct multi-threaded programs.</p> <p>Clojure is very concise, requiring very little code to express complex operations.</p> <p>Data centric design - a well constructed data structure helps define and clarify the purpose of the code</p> <p>Modularity - Clojure and its community build things in modules / components that work together (in a similar design approach to the Unix file system, for example).</p> <p>It offers a REPL and dynamic type system: ideal for beginners to experiment with, and well-suited for manipulating complex data structures.</p> <p>A consistently designed standard library and full-featured set of core data types rounds out the Clojure toolbox.</p> <p>Clojure is close to the speed of Java</p>"},{"location":"introduction/concepts/misc/#constraints","title":"Constraints","text":"<p>Clojure relies on the JVM so there can be a longer boot time than a scripting language like Javascript.  However, as you can connect to the Clojure runtime (the REPL) of a live system and because Clojure is dynamic, you can make changes to that live system without any downtime.</p> <p>If you require more performance from Clojure, you can specify ahead of time compilation.</p>"},{"location":"introduction/concepts/naming-local/","title":"Naming - local scope","text":""},{"location":"introduction/concepts/naming-local/#local-names-in-functions","title":"Local names in functions","text":"<p>You can define names for things within the scope of a function using the <code>let</code> function.</p>"},{"location":"introduction/concepts/naming-local/#example","title":"Example","text":"<p>You can use the let function to define a simple expression, for which everything will go out of scope once it has been evaluated</p> <pre><code>(let [local-name \"some value\"])\n(let [minutes-in-a-day (* 60 60 24)])\n</code></pre> <p>You can also use <code>let</code> inside a function to do something with the arguments passed to that function.  Here we calculate the hourly-rate from a yearly salary, returning the calculated-rate.</p> <p>(defn hourly-rate [yearly-salary weeks-in-year days-in-week]   (let [calculated-rate (/ yearly-salary weeks-in-year days-in-week)]     calculated-rate))</p> <p>(hourly-rate 60000 48 5)</p> <pre><code>## Local names in data structures\n\n  When defining a map you are creating a series of key value pairs.  The key is essentially a name that represents the value it is paired with.  Keys are often defined using a `:keyword`.\n\n```clojure\n  {:radius 10, :pi 22/7 :colour purple}\n\n  (def my-circle {:radius 10, :pi 22/7 :colour purple})\n</code></pre> <p>Fixme This is incorrect, as a Clojure keyword type (a name starting with :) have global scope within a namespace.  If the keys were strings, then they would have the scope of just the collection.</p>"},{"location":"introduction/concepts/naming-things/","title":"Naming things - data structures and functions","text":"<p>The <code>def</code> function is used to name data structures in Clojure.</p> <p>You can also use <code>def</code> to name functions, however it is more common to use <code>defn</code> (which is a macro around def) to give a function a name.</p>"},{"location":"introduction/concepts/naming-things/#keeping-things-private","title":"Keeping things private","text":"<p>There is less emphasis on keeping functions and data structures private (compared to Java, C++, C#).  If you want to define a function name so that it is only accessible by other functions of the same namespace, you can use the <code>defn-</code> function.</p> <p>There is no private equivalent for <code>def</code> (as of Clojure 1.6) however you can use metadata to specify this</p> <p>(def ^:private name data)</p> <p>TODO: check if there is anything new around this or other common practices</p>"},{"location":"introduction/concepts/naming-things/#misc-writing-a-private-def-macro","title":"Misc - writing a private def macro","text":"<p>You could write your own macro to create a private <code>def</code> called <code>def-</code></p> <pre><code>(defmacro def- [item value]\n  `(def ^{:private true} ~item ~value)\n)\n</code></pre> <p>There are no naming conventions for a private symbol name.  As its defined an used within the scope of that one namespace (file), then there is no real need to make a special convention.  Private functions will just be called as normal within the namespace and it will be quite clear from the function definition that it is private.</p> <p>Clojure community style guide</p>"},{"location":"introduction/concepts/naming-things/#example","title":"example","text":"<p>Learning Clojure #4: private functions http://tech.puredanger.com/2010/02/09/clojure-4-private-functions/</p> <p>Sometimes in a Clojure file you just want some helper functions that shouldn\u2019t be exposed outside the namespace. You can create a private function using the special defn- macro instead of defn.</p> <p>For instance, create a file foo/bar.clj with a public and a private function:</p> <p>(ns foo.bar) (defn- sq [x] (* x x)) (defn sum-squares [a b] (+ (sq a) (sq b)))</p> <p>Then use it from the REPL:</p> <p>user=&gt; (use 'foo.bar) nil user=&gt; (sum-squares 3 4) 25 user=&gt; (sq 5) java.lang.Exception: Unable to resolve symbol: sq in this context (NO_SOURCE_FILE:6)</p>"},{"location":"introduction/concepts/purpose/","title":"When to use Clojure","text":"<p>Clojure is a general purpose language suitable for any kind of application or service.  As Clojure implementations run across multiple technology platforms and operating systems, there are very few barriers to its use.</p> <p>So Clojure is great for webapps, data science, big data, finance industry (banking, trading, insurance, etc), devops tools (log analysis, etc) and anything else really.</p> <p>There are areas where Clojure obviously excels.</p>"},{"location":"introduction/concepts/purpose/#effective-data-manipulation","title":"Effective Data Manipulation","text":"<p>Fundamentally all software systems take in data (in the form of values or events), process or react to that data and return as a result.</p> <p>The persistent data structures in Clojure (list, vector, hash-map and set) provide an efficient way to use immutable collections of data.</p> <p>The <code>clojure.core</code> library contains a vast number of data processing functions in Clojure so data is easily transformed</p>"},{"location":"introduction/concepts/purpose/#highly-scalable","title":"Highly Scalable","text":"<p>Clojure code is encouraged to be immutable and functions to be pure, you can run millions of parallel instances of your application or service for massive processing power.  These features also vastly simplify concurrent programming.</p>"},{"location":"introduction/concepts/purpose/#reducing-complexity","title":"Reducing Complexity","text":"<p>Clojure encourages a component design through functional composition, breaking down problems into components</p> <p>Clojure and its libraries are all great examples of well designed components and the community strongly encourages this approach.</p>"},{"location":"introduction/concepts/purpose/#hintfunctional-reactive-programming","title":"Hint::Functional Reactive Programming","text":"<p>You can also use ClojureScript for Functional Reactive programming of client-side apps for browsers and mobile device.</p>"},{"location":"introduction/concepts/rationale/","title":"The rationale for Clojure","text":"<p>At the time Clojure was created there were no LISP based languages that ran on a widely adopted platform, that also made concurrency easier for the developer to manage.</p> <p>Developers and the companies that hire them are comfortable with the performance, security and stability of the Java Virtual Machine.</p> <p>While Java developers may envy the succinctness, flexibility and productivity of dynamic languages, they have concerns about running on customer-approved infrastructure, access to their existing code base and libraries, and performance. In addition, they face ongoing problems dealing with concurrency using native threads and locking. Clojure is an effort in pragmatic dynamic language design in this context. It endeavors to be a general-purpose language suitable in those areas where Java is suitable. It reflects the reality that, for the concurrent programming future, pervasive, uncontrolled mutation simply has to go.</p> <p>Clojure meets its goals by: embracing an industry-standard, open platform - the JVM; modernizing a venerable language - Lisp; fostering functional programming with immutable persistent data structures; and providing built-in concurrency support via software transactional memory and asynchronous agents. The result is robust, practical, and fast.</p> <p>Clojure has a distinctive approach to state and identity.</p> <p>Why Clojure?</p>"},{"location":"introduction/concepts/rationale/#motivating-ideas-behind-clojure","title":"Motivating ideas behind Clojure","text":"<p>A LISP base language design is very effecitve</p> <ul> <li> <p>Lambda calculus yields an extremely small core with very little syntax required</p> </li> <li> <p>Core advantage still code-as-data and syntactic abstraction</p> </li> </ul> <p>Standard Lisps (Common Lisp, Scheme) have not evolved over time, since standardisation.  Their core data structures are mutable and not extensible and therefore no mechanisms for effectively dealing with concurrency.</p> <p>Clojure is a Lisp not constrained by backwards compatibility, allowing modernisation of the language that otherwise deters developers from adoption.</p> <p>Clojure extends the code-as-data paradigm to maps and vectors</p> <p>All data structures default to immutability</p> <p>Core data structures are extensible abstractions</p> <p>Embraces a platform (JVM)</p> <p>Functional programming is a good thing</p> <ul> <li>Immutable data + first-class functions</li> <li>Could always be done in Lisp, by discipline/convention</li> </ul> <p>But if a data structure can be mutated, dangerous to presume it won't be In traditional Lisp, only the list data structure is structurally recursive Pure functional languages tend to strongly static types Not for everyone, or every task Clojure is a functional language with a dynamic emphasis All data structures immutable &amp; persistent, supporting recursion Heterogeneous collections, return types Dynamic polymorphism Languages and Platforms VMs, not OSes, are the platforms of the future, providing: Type system Dynamic enforcement and safety Libraries Abstract away OSes Huge set of facilities Built-in and 3rd-party Memory and other resource management GC is platform, not language, facility Bytecode + JIT compilation Abstracts away hardware Language as platform vs. language + platform Old way - each language defines its own runtime GC, bytecode, type system, libraries etc New way (JVM, .Net) Common runtime independent of language Language built for platform vs language ported-to platform Many new languages still take 'Language as platform' approach When ported, have platform-on-platform issues Memory management, type-system, threading issues Library duplication If original language based on C, some extension libraries written in C don't come over Platforms are dictated by clients 'Must run on JVM' or .Net vs 'must run on Unix' or Windows JVM has established track record and trust level Now also open source Interop with other code required C linkage insufficient these days Java/JVM is a language and platform Not the original story, but other languages for JVM always existed, now embraced by Sun Java can be tedious, insufficiently expressive Lack of first-class functions, no type inference, etc Ability to call/consume Java is critical Clojure is the language, JVM the platform Object Orientation is overrated Born of simulation, now used for everything, even when inappropriate Encouraged by Java/C# in all situations, due to their lack of (idiomatic) support for anything else Mutable stateful objects are the new spaghetti code Hard to understand, test, reason about Concurrency disaster Inheritance is not the only way to do polymorphism \"It is better to have 100 functions operate on one data structure than to have 10 functions operate on 10 data structures.\" - Alan J. Perlis Clojure models its data structures as immutable objects represented by interfaces, and otherwise does not offer its own class system. Many functions defined on few primary data structures (seq, map, vector, set). Write Java in Java, consume and extend Java from Clojure. Polymorphism is a good thing Switch statements, structural matching etc yield brittle systems Polymorphism yields extensible, flexible systems Clojure multi-methods decouple polymorphism from OO and types Supports multiple taxonomies Dispatches via static, dynamic or external properties, metadata, etc Concurrency and the multi-core future Immutability makes much of the problem go away Share freely between threads But changing state a reality for simulations and for in-program proxies to the outside world Locking is too hard to get right over and over again Clojure's software transactional memory and agent systems do the hard part</p> <p>In short, I think Clojure occupies a unique niche as a functional Lisp for the JVM with strong concurrency support. Check out some of the features.</p>"},{"location":"introduction/concepts/what-is-functional-programming/","title":"What is Functional Programming","text":"<p>Functional programming can seem quite different from imperative programming used in languages like C, C++ and Java.</p> <p>Imperative languages may seem easier initially, as defining one step after another is familiar approach to many things in live.  As the scale of a system grows, so does complexity.  Imperative languages applied object oriented design to manage complexity with varied rates of success.</p> <p>When shared mutable state is common in an OO design, then a system quickly becomes complex and very difficult to reason about.</p> <p>Functional programming is actually simpler that the OO approach, although initially it may be unfamiliar and not considered as easy.  As systems grow in complexity, the building blocks are still simple and deterministic, creating a system that is far easier to reason about.</p>"},{"location":"introduction/concepts/what-is-functional-programming/#imperative-programming-languages","title":"Imperative programming languages","text":"<p>In Imperative languages code is written that specifies a sequential of instructions that complete a task.  These instructions typically modifies program state until the desired result is achieved.</p> <p>Variables typically represent memory addresses that are mutable (can be changed) by default.</p> <p></p>"},{"location":"introduction/concepts/what-is-functional-programming/#functional-programming-languages","title":"Functional programming languages","text":"<p>Individual tasks are small and achieved by passing data to a function which returns a result.</p> <p>Functions are composed together to form more complex tasks and satisfy larger business logic.  These composed functions pass the result of their evaluation to the next function, until all functions in the composition have been evaluated.</p> <p>The entire functional program can be thought of as a single function defined in terms of smaller ones.</p> <p>Program execution is an evaluation of expressions, with the nesting structure of function composition determining program flow.</p> <p>Data is immutable and cannot be change once created.  Changes are expressed as new values, with complex values sharing common values for efficiency.</p> <p></p>"},{"location":"iterate-over-data/","title":"Iterate over data","text":"<p>Clojure data is typically within one or more of the built in collection types (vector, map, list, set).</p> <p>We can use some functions in Clojure core directly on these collection types.  Other clojure core functions need a little help.</p>"},{"location":"iterate-over-data/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/#map","title":"map","text":"<p>Used to create a new collection by applying a given function to each element of the collection in turn.</p> <pre><code>(map inc [1 2 3])\n</code></pre> <p>If there are multiple collections, map returns a new collection with values created by calling the function with a value from each of the collections.  Once map reaches the end of one collection it stops and returns the result.</p> <pre><code>(map + [1 2 3] [4 5 6] [7 8 9])\n</code></pre>"},{"location":"iterate-over-data/#apply","title":"apply","text":"<p>Used to remove all the values from a collection so they are treated as individual arguments to the function given to apply.</p> <pre><code>(= (apply + [1 2 3])\n   (+ 1 2 3))\n</code></pre>"},{"location":"iterate-over-data/#reduce","title":"reduce","text":"<p>reduce can be used in a similar way as apply, to transform a collection into a different value.</p> <p>reduce can also take an argument referred to as an accumulator, used to keep local state as reduce iterates through the values in the collection.</p> <p>A function used with reduce is called a reducing function and is a more abstract approach to loop/recur although its possible to give your reducing function a name so is more reusable.</p>"},{"location":"iterate-over-data/#threading-macros","title":"threading macros","text":"<p>Write code that reads as a sequential series of function calls, rather that the nested function calls typical in lisp.</p> <p>A threading macro is often used to thread a collection through a number of function calls and expressions.</p>"},{"location":"iterate-over-data/#comp","title":"comp","text":"<p>Compose functions together that work over a collection.  It can be seen as a more abstract approach to a threading macro or nested function calls.</p>"},{"location":"iterate-over-data/#transduce","title":"transduce","text":"<p>Used like comp to create a pipeline of function calls, however, each function call or expression must return a transducer (transforming reduction).  Many <code>clojure.core</code> functions return a transducer if you do not provide the collection argument.</p>"},{"location":"iterate-over-data/apply/","title":"apply","text":""},{"location":"iterate-over-data/apply/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/comp/","title":"comp - composing functions","text":""},{"location":"iterate-over-data/comp/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/filter-remove/","title":"filter and remove","text":"<p>Use filter and remove with predicate functions, those returning true or false, to create a sub-set of the data.</p> <p>filter creates a new collection that contains all the matching values from the predicate function (true).</p> <p><code>remove</code> creates a new collection with contains all the values that didn't match the predicate function (false).</p> <pre><code>(filter odd? [1 2 3 4 5 6 7 8 9])\n</code></pre>"},{"location":"iterate-over-data/filter-remove/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map-fn/","title":"map with fn - anonymous function","text":"<pre><code>(map (fn [arg] (+ arg 5)) [1 2 3 4 5])\n</code></pre> <p>There is a syntactic short-cut for the anonymous function that does not require a name for the arguments</p> <p><code>#(+ %1 5)</code></p> <p>Adding this into our previous expression we can see that its still quite readable and helps keep the code clean.</p> <pre><code>(map #(+ arg 5) [1 2 3 4 5])\n</code></pre>"},{"location":"iterate-over-data/map-fn/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map-fn/#hintanonymous-function-name","title":"Hint::Anonymous function name","text":"<p>Anonymous functions do not have an externally referable name, so must be used in-line with an expression.</p> <p>The <code>fn</code> function can be defined with a name, however, this is only available in the scope of that function definition, the name cannot be used to refer to that function outside of its definition.</p> <p>Including a name within a <code>fn</code> definition enables the function to call itself, therefore creating an anonymous recursive function.</p>"},{"location":"iterate-over-data/map-partial/","title":"map with partial","text":""},{"location":"iterate-over-data/map-partial/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map/","title":"map function","text":""},{"location":"iterate-over-data/map/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Add examples of using the map function with data</p>"},{"location":"iterate-over-data/reduce/","title":"reduce","text":""},{"location":"iterate-over-data/reduce/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/transduce/","title":"transduce and transforming reducers","text":""},{"location":"iterate-over-data/transduce/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"libraries/","title":"Libraries","text":""},{"location":"libraries/clojars/","title":"Clojars","text":""},{"location":"libraries/clojure-core-lisp-comprehension/","title":"Libraries: <code>clojure.core</code> lisp comprehension","text":""},{"location":"libraries/clojure-core-lisp-comprehension/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>discuss functions for list comprehension <code>for</code></p>"},{"location":"libraries/clojure-core/","title":"Understanding Clojure Libraries: <code>clojure.core</code>","text":""},{"location":"libraries/clojure-core/#warningvery-rough-draft-of-an-idea","title":"Warning::Very rough draft of an idea","text":"<p>Experimenting with the value of grouping functions in clojure.core to help ensure you are exposed to most of the concepts in Clojure</p>"},{"location":"libraries/clojure-core/#families-of-functions","title":"Families of functions","text":"<ul> <li>List Comprehension (for, while, )</li> <li> <p>used to process multiple collections</p> </li> <li> <p>Transformations (map, filter, apply, reduce )</p> </li> <li>transform the contents of a collection</li> </ul>"},{"location":"libraries/edn/","title":"edn","text":""},{"location":"libraries/om/","title":"om","text":""},{"location":"modifying-data-structures/","title":"Modifying data structures","text":"<p>Wait, I thought you said that data structures were immutable!  So how can we change them then?</p> <p>Yes, lists, vectors, maps and sets are all immutable.  However, you can get a new data structure that has the changes you want. To make this approach efficient, the new data structure contains only the new data and links back to the existing data structure for shared data elements.</p> <p>We will see some of the most common functions that work with data structures in this section.  In actuality, everything can be considered a function that works on a data structure though, as that is the language design of clojure.</p>"},{"location":"modifying-data-structures/lists/","title":"Lists","text":"<p>You can change lists with the <code>cons</code> function, see <code>(doc cons)</code> for details</p> <p>(cons 5 '(1 2 3 4))</p> <p>You will see that <code>cons</code> does not change the existing list, it create a new list that contains the number 5 and a link to all the elements of the existing list.</p> <p>You can also use cons on vectors <code>(cons 5 [1 2 3 4])</code></p> <pre><code>(cons \"fish\" '(\"and\" \"chips\"))\n\n(conj '(1 2 3 4) 5)\n\n(conj [1 2 3 4] 5)\n\n\n;; Lets define a simple list and give it a name\n(def list-one '(1 2 3))\n\n;; the name evaluates to what we expect\nlist-one\n\n;; If we add the number 4 using the cons function, then we\n;; get a new list in return, with 4 added to the front (because thats how lists work with cons)\n(cons 4 list-one)\n\n;; If we want to keep the result of adding to the list, we can assign it a different name\n(def list-two (cons 4 list-one))\n;; and we get the result we want\nlist-two\n\n;; we can also pass the original name we used for the list to the new list\n(def list-one (cons 4 list-one))\n\n;; If we re-evaluate the definition above, then each time we will get an extra\n;; number 4 added to the list.\n\nlist-one\n\n;; Again, this is not changing the original list, we have just moved the name\n;; of the list to point to the new list.\n;; Any other function working with this data structure before reassigning the name\n;; will not be affected by the re-assignment and will use the unchanged list.\n</code></pre>"},{"location":"modifying-data-structures/maps/","title":"Maps","text":"<p>The <code>conj</code> function works on all of the Clojure collections.  The map collection also has functions that affect the evaluation of a map and the value of map returned.</p>"},{"location":"modifying-data-structures/maps/#adding-new-values-with-conj","title":"Adding new values with <code>conj</code>","text":"<p>If you have a collection of maps, you can add another map to that collection with the <code>conj</code> function.</p> <pre><code>(conj [{:map1 1}] {:map2 2})\n\n;; =&gt; [{:map1 1} {:map2 2}]\n</code></pre>"},{"location":"modifying-data-structures/maps/#changing-values-with-assoc","title":"Changing values with <code>assoc</code>","text":"<p>The <code>assoc</code> function is used to update a value in a map without necessary being concerned about the current value.  <code>assoc</code> returns a complete new map with the specified value.</p> <pre><code>(assoc {:food \"Fish\"} :food \"Fish&amp;Chips\")\n\n;; =&gt; {:food \"Fish&amp;Chips\"}\n</code></pre> <p>It does not matter how many keys are in the map, as keys are unique, then <code>assoc</code> will look up the specific key and change its value to that specified in the third argument.</p> <p>If a key is not in the map, <code>assoc</code> will add both the key and the value.</p> <pre><code>(def alphabet-soup {:a 1 :b 2 :c 3})\n\n(assoc alphabet-soup :d 4)\n\n;; =&gt; {:a 1, :b 2, :c 3, :d 4}\n</code></pre> <p>If there are multiple levels to the structure of your map, ie. the value of a key in the map is also a map</p> <p>For example, the value of <code>:luke</code> in the <code>star-wars-characters</code> map is represented as a map too <code>{:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}</code></p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Crank phone calls\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"}})\n</code></pre> <p>To update the skill of one of the characters we can use <code>assoc-in</code> to update the correct value by traversing the map via the given keys.</p> <pre><code>(assoc-in star-wars-characters [:vader :skill] \"The Dark Side of the Force\")\n\n;; =&gt; {:luke {:fullname \"Luke Skywalker\", :skill \"Targeting Swamp Rats\"},\n       :vader {:fullname \"Darth Vader\", :skill \"The Dark Side of the Force\"},\n       :jarjar {:fullname \"JarJar Binks\", :skill \"Upsetting a generation of fans\"}}\n</code></pre>"},{"location":"modifying-data-structures/maps/#update-values-in-a-map-with-update","title":"Update values in a map with <code>update</code>","text":"<p>Rather than replace the current value with one specified, <code>update</code> applies a function to the existing value in order to update that value.</p> <pre><code>(def alphabet-soup {:a 1 :b 2 :c 3})\n\n(update alphabet-soup :a inc)\n\n;; =&gt; {:a 2, :b 2, :c 3}\n</code></pre> <p>Hint As with <code>assoc</code> you can also use <code>update</code> on nested maps using the <code>update-in</code> function.</p>"},{"location":"modifying-data-structures/sets/","title":"Sets","text":""},{"location":"modifying-data-structures/vectors/","title":"Vectors","text":""},{"location":"performance/","title":"Clojure Performance and benchmarks","text":"<p>There are several aspects to performance testing</p> <ul> <li>time taken by individual functions / expressions</li> <li>time through a specific path in your application</li> <li>response times under different loads</li> </ul> <p>The purpose of performance testing and bench-marking is to understand the expected behaviour of your application under various usage patterns.  This kind of testing can also suggest areas of the application that might benefit from optimisation</p>"},{"location":"performance/#performance-tools-for-clojure","title":"Performance tools for Clojure","text":"<ul> <li>Criterium - benchmarks for Clojure expressions</li> <li>Gatling</li> </ul>"},{"location":"performance/#gatling","title":"Gatling","text":"<p>The Gatling Project is a free and open source performance testing tool. Gatling has a basic GUI that's limited to test recorder only. However, the tests can be developed in easily readable/writable domain-specific language (DSL).</p> <p>Key Features of Gatling:</p> <ul> <li>HTTP Recorder</li> <li>An expressive self-explanatory DSL for test development</li> <li>Scala-based</li> <li>Production of higher load using an asynchronous non-blocking approach</li> <li>Full support of HTTP(S) protocols and can also be used for JDBC and JMS load testing</li> <li>Multiple input sources for data-driven tests</li> <li>Powerful and flexible validation and assertions system</li> <li>Comprehensive informative load reports</li> </ul>"},{"location":"performance/#reference-other-performance-tools","title":"Reference: Other performance tools","text":"<p>Other notable performance tools include:</p> <ul> <li>The Grinder</li> <li>Apache JMeter (Java desktop app)</li> <li>Tsung (required Erlang)</li> <li>Locust (python)</li> </ul> <p>Key Features of The Grinder:</p> <ul> <li>TCP proxy to record network activity into the Grinder test script</li> <li>Distributed testing that scales with an the increasing number of agent instances</li> <li>Power of Python or Closure, combined with any Java API, for test script creation or modification</li> <li>Flexible parameterization, which includes creating test data on the fly and the ability to use external data sources like files and databases</li> <li>Post-processing and assertion with full access to test results for correlation and content verification</li> <li>Support of multiple protocols</li> </ul> <p>Key Features of JMeter:</p> <ul> <li>Desktop GUI tool</li> <li>Cross-platform. JMeter can run on any operating system with Java</li> <li>Scalable. When you need a higher load than a single machine can create, JMeter can execute in a distributed mode, meaning one master JMeter machine controls a number of remote hosts.</li> <li>Multi-protocol support. The following protocols are all supported out-of-the-box: HTTP, SMTP, POP3, LDAP, JDBC, FTP, JMS, SOAP, TCP</li> <li>Multiple implementations of pre- and post-processors around sampler. This provides advanced setup, teardo* wn parametrization, and correlation capabilities</li> <li>Various assertions to define criteria</li> <li>Multiple built-in and external listeners to visualize and analyze performance test results</li> <li>Integration with major build and continuous integration systems, making JMeter performance tests part of the full software development life cycle</li> <li>Extensions via plugins</li> </ul>"},{"location":"performance/#resources","title":"Resources","text":"<ul> <li>Open source load testing tools - which one should you use</li> </ul>"},{"location":"performance/load-testing/","title":"Load Testing","text":"<p>The Gatling project can be used to create and run load tests using Clojure (and get fancy reports).</p> <p>Add the following to your project.clj :dependencies</p> <pre><code>[clj-gatling \"0.11.0\"]\n</code></pre>"},{"location":"performance/load-testing/#describe-a-load-test","title":"Describe a Load Test","text":"<p>This is how we would write a simple load test which performs 50 GET requests against a server running at test.com:</p> <pre><code>class SimpleSimulation extends Simulation {\n  //declare a scenario with a simple get request performed 5 times\n  val scn = scenario(\"myScenario\")\n            .exec(http(\"myRequest\").get(\"http://test.com/page.html\"))\n            .repeat(5)\n\n  //run the scenario with 10 concurrent users\n  setUp(scn.users(10))\n}\n</code></pre> <p>Gatling refers to load tests as Simulations which have one or more Scenarios. In the one above we are saying we will have 10 users execute 5 requests each in parallel. We could provide a Content-Type header with the request and check for a 200 response code like this:</p> <pre><code>http(\"myRequest\")\n  .get(\"http://test.com/page.html\")\n  .header(\"Content-Type\", \"text/html\")\n  .check(status.is(200))\nIf we wanted to do a POST request with a JSON body and basic authentication, as well as verify something in the response:\n\nhttp(\"myRequest\")\n  .post(\"http://test.com/someresource\"))\n  .body(StringBody(\"\"\"{ \"myContent\": \"myValue\" }\"\"\"))\n  .asJSON\n  .basicAuth(\"username\", \"password\")\n  .check(jsonPath(\"$..someField\").is(\"some value\"))\n</code></pre> <p>The expression used to extract someField from the response is passed to jsonPath() and is based on Goessner\u2019s JsonPath syntax. We use is() to verify the expected value is equal to some value. We can also do other forms of verification on the response json like:</p> <ul> <li>not(expectedValue): not equal to expectedValue</li> <li>in(sequence): to check that a value belongs to the given sequence</li> <li>exists(), notExists(): to check for the presence/absence of a field</li> </ul> <p>For a multipart request with 2 parts and gzip compression:</p> <pre><code>http(\"myRequest\")\n  .post(\"http://test.com/someresource\"))\n  .bodyPart(StringBodyPart(\"\"\"{ \"myContent\": \"myValue\" }\"\"\"))\n  .bodyPart(RawFileBodyPart(\"file\", \"test.txt\")\n  .processRequestBody(gzipBody)\nWe can also create scenarios with multiple requests and use the result from previous requests in subsequent requests like this:\n\nscenario(\"myScenario\")\n  .exec(http(\"request1\")\n          .post(\"http://test.com/resource1\")\n          .body(StringBody\"\"\"{ \"myContent\": \"\"}\"\"\")\n          .check(jsonPath(\"$..myResponse.guid\").saveAs(\"guid\")))\n  .exec(http(\"request2\")\n          .put(\"http://test.com/resource2/${guid}\")\n          .body(StringBody\"\"\"{ \"someOtherField\": \"\"}\"\"\"))\n</code></pre> <p>guid is extracted from the response of the first call using saveAs(\"guid\") and used in the path to the PUT call.</p> <p>Scenarios can also be run with a ramp up. If we wanted to run the scenario above with 1000 users with a ramp up of 20 seconds we would do:</p> <pre><code>setUp(scn.users(1000).ramp(20))\n</code></pre>"},{"location":"performance/load-testing/#run-a-simulation","title":"Run a Simulation","text":"<p>There are a number of ways to run Gatling simulations. You can download the bundle, place your simulations under the user-files/simulations directory and then run bin/gatling.sh.</p> <p>If you prefer integration with your build system there are plugins for Maven, Gradle and SBT. For example, for Maven we just add the dependencies in the pom.xml:</p> <pre><code>&lt;dependencies&gt;\n  &lt;dependency&gt;\n    &lt;groupId&gt;io.gatling.highcharts&lt;/groupId&gt;\n    &lt;artifactId&gt;gatling-charts-highcharts&lt;/artifactId&gt;\n    &lt;scope&gt;test&lt;/scope&gt;\n  &lt;/dependency&gt;\n&lt;/dependencies&gt;\n\n&lt;build&gt;\n   &lt;plugins&gt;\n     &lt;plugin&gt;\n       &lt;groupId&gt;io.gatling&lt;/groupId&gt;\n       &lt;artifactId&gt;gatling-maven-plugin&lt;/artifactId&gt;\n     &lt;/plugin&gt;\n   &lt;/plugins&gt;\n&lt;/build&gt;\n</code></pre> <p>Place simulations under src/test/scala/com/company/service and then in the terminal:</p> <pre><code>mvn gatling:execute -Dgatling.simulationClass=com.company.service.YourSimulation\n</code></pre>"},{"location":"performance/testing-functions/","title":"Testing Functions","text":""},{"location":"performance/testing-functions/#adding-the-criterium-library","title":"Adding the Criterium library","text":"<p>Add <code>[criterium \"0.4.4\"]</code> to you <code>project.clj</code> file.</p> <p>Add criterium to the namespace were you run your tests</p> <pre><code>(ns ,,,\n  :require [criterium.core] :refer [quick-bench])\n</code></pre> <p>Or simply require criterium in the REPL</p> <pre><code>(require '[criterium.core] :refer [quick-bench])\n</code></pre>"},{"location":"performance/testing-functions/#using-criterium-to-test-code","title":"Using Criterium to test code","text":"<p>Lets try a few similar Clojure functions to see the Criterium benchmark in action</p> <pre><code>(let [number 5]\n  (quick-bench (cond = 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <p>Benchmark output is sent to the REPL</p> <pre><code>Evaluation count : 50788488 in 6 samples of 8464748 calls.\n             Execution time mean : 2.535916 ns\n    Execution time std-deviation : 0.096838 ns\n   Execution time lower quantile : 2.435814 ns ( 2.5%)\n   Execution time upper quantile : 2.686146 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 13.8889 % Variance is moderately inflated by outliers\n</code></pre> <p>Running the benchmark again for the same expression, we get pretty consistent results</p> <pre><code>Evaluation count : 50408712 in 6 samples of 8401452 calls.\n             Execution time mean : 2.571379 ns\n    Execution time std-deviation : 0.163071 ns\n   Execution time lower quantile : 2.366952 ns ( 2.5%)\n   Execution time upper quantile : 2.721099 ns (97.5%)\n                   Overhead used : 9.431514 ns\n</code></pre> <p>There is a parallized version of <code>cond</code> called <code>condp</code>.</p> <pre><code>(let [number 5]\n  (quick-bench (condp = 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <pre><code>Evaluation count : 3625284 in 6 samples of 604214 calls.\n             Execution time mean : 156.813816 ns\n    Execution time std-deviation : 2.560629 ns\n   Execution time lower quantile : 154.222522 ns ( 2.5%)\n   Execution time upper quantile : 160.425030 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 13.8889 % Variance is moderately inflated by outliers\n</code></pre> <p>That figure is quite high, lets run that again.</p> <pre><code>Evaluation count : 3707922 in 6 samples of 617987 calls.\n             Execution time mean : 154.219102 ns\n    Execution time std-deviation : 3.427811 ns\n   Execution time lower quantile : 149.777377 ns ( 2.5%)\n   Execution time upper quantile : 159.225180 ns (97.5%)\n                   Overhead used : 9.431514 ns\n</code></pre> <p>So using a parallized version of a function adds a significant exectution time.  I believe the extra time is due to setting up a thread.  If so, then when using <code>condp</code> you only get a more effective throughput when running multiple parallel threads, which should be fairly obvious.</p> <p>Now lets benchmark a similar function called <code>case</code>.  This function is nicely optimised on the JVM especially when the values are sequential, so we should see faster results</p> <pre><code>(let [number 5]\n  (quick-bench (case 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <p>Benchmark output is sent to the REPL</p> <pre><code>Evaluation count : 56533626 in 6 samples of 9422271 calls.\n             Execution time mean : 1.158650 ns\n    Execution time std-deviation : 0.187322 ns\n   Execution time lower quantile : 1.021431 ns ( 2.5%)\n   Execution time upper quantile : 1.471115 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 47.5092 % Variance is moderately inflated by outliers\n</code></pre>"},{"location":"puzzles/","title":"Puzzles","text":"<p>Simple puzzles to help you start thinking functionally</p>"},{"location":"puzzles/random-seat-assignment/","title":"Random Seat assignment","text":"<p>https://github.com/practicalli/clojure-practicalli-content/issues/4</p> <p>Take a functional / data oriented approach to solving this problem</p>"},{"location":"puzzles/random-seat-assignment/#description","title":"Description","text":"<p>You want to randomly assign seating to a number of people for a fixed number of seats. Each seat is represented by an integer number between 1 and 30.</p> <p>How do you randomly assign seats without choosing the same seat twice.</p>"},{"location":"puzzles/random-seat-assignment/#loop-recur-approach","title":"Loop / recur approach","text":"<p>Bad...</p>"},{"location":"puzzles/random-seat-assignment/#recursive-function","title":"recursive function","text":""},{"location":"quickstart/quick-reference/","title":"Clojure Quick Reference","text":"<p>The basic Clojure syntax and a few common functions you should probably learn first.</p> <p>Also see the Clojure.org cheat-sheet</p>"},{"location":"quickstart/quick-reference/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is treated as a call to a function. This is known as prefix notation which greatly simplifies Clojure syntax and makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p> <pre><code>(+ 2 3 5 8 13 (* 3 7))\n(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n(clojure-version)\n</code></pre> <p>Functions contain doc-strings and you can ask for a functions documentation, or show the source code.</p> <pre><code>(doc doc)\n(source doc)\n</code></pre> <p>Clojure is a dynamically typed language, it is also strongly typed (everything is a type, but you dont have to express the type in your code).  The type of anything in Clojure can be returned.</p> <pre><code>(type 42)\n(type {:hash \"data\" :map \"more data\"})\n</code></pre>"},{"location":"quickstart/quick-reference/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <pre><code>(str \"lists used mainly\" (* 2 2) :code)\n\n[0 \"indexed array\"]\n\n{:key \"value\" :pairs \"hash-map\" :aka \"dictionary\"}\n\n#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre>"},{"location":"quickstart/quick-reference/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>Names can be bound to any values, simple values like numbers, collections or functions.  A convenient way to refer to value in your code.</p> <pre><code>(def public-health-data\n  ({:date \"2020-01-01\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-03\" :confirmed-cases 23014 :recovery-percent 15}))\n\n(def add-hundred (partial + 100))\n</code></pre>"},{"location":"quickstart/quick-reference/#map-reduce-filter","title":"map reduce filter","text":"<p>Common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n\n(filter even? [1 3 5 8 13 21 34])\n\n(reduce + [31 28 30 31 30 31])\n</code></pre>"},{"location":"quickstart/quick-reference/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p>"},{"location":"quickstart/quick-reference/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(fn [x] (* x x))\n\n(map (fn [x] (* x x)) [1 2 3 4 5])\n</code></pre>"},{"location":"quickstart/quick-reference/#ratio-type","title":"Ratio Type","text":"<p>; Using the division function (/ ) shows another interesting characteristic of Clojure, the fact that it is lazy.  This is not lazy in a bad way, but lazy evaluation of data structures.  This actually helps to make clojure more efficient at dealing with data, especially very large data sets.</p> <pre><code>(/ 22 7)\n22/7\n\n(/ 22 7.0)\n3.142857142857143\n\n(type (/ 22 7))\n</code></pre> <p>Using a Ratio means that the mathematical division is not evaluated when using whole numbers (Integers) that would produce a decimal number.  If you do return a decimal number then what precision of decimal are you expecting.  By specifying one or more of the numbers as a decimal value you are giving Clojure a precision to infer and can therefore provide a specific decimal result.</p>"},{"location":"quickstart/quick-reference/#java-interoperability","title":"Java interoperability","text":"<p><code>.</code> and <code>new</code> are Clojure functions that create a Java object. This allows you to use values from Java constants, i.e. PI is a static double from the java.lang.Math object</p> <pre><code>(. Math PI)\n3.141592653589793\n</code></pre> <p>Also call static and instance methods from Java objects.</p> <pre><code>(Math/cos 3)\n\n(javax.swing.JOptionPane/showMessageDialog nil\n    \"Hello Java Developers\")\n</code></pre>"},{"location":"quickstart/quick-reference/#recursion","title":"Recursion","text":"<p>Recursive function</p> <pre><code>(defn recursive-counter\n  [value]\n  (if (&lt; value 1000)\n    (recur (+ value 25))))\n\n(recursive-counter 100)\n</code></pre>"},{"location":"reference/","title":"Reference","text":""},{"location":"reference/basic-syntax/","title":"Reference: Basic Syntax","text":""},{"location":"reference/basic-syntax/#notes-from-aphyr","title":"Notes from Aphyr","text":"<p>Let\u2019s write a simple program. The simplest, in fact. Type \u201cnil\u201d, and hit enter.</p> <p>user=&gt; nil nil nil is the most basic value in Clojure. It represents emptiness, nothing-doing, not-a-thing. The absence of information.</p> <p>user=&gt; true true user=&gt; false false true and false are a pair of special values called Booleans. They mean exactly what you think: whether a statement is true or false. true, false, and nil form the three poles of the Lisp logical system.</p> <p>user=&gt; 0 0 This is the number zero. Its numeric friends are 1, -47, 1.2e-4, 1/3, and so on. We might also talk about strings, which are chunks of text surrounded by double quotes:</p> <p>user=&gt; \"hi there!\" \"hi there!\" nil, true, 0, and \"hi there!\" are all different types of values; the nouns of programming. Just as one could say \u201cHouse.\u201d in English, we can write a program like \"hello, world\" and it evaluates to itself: the string \"hello world\". But most sentences aren\u2019t just about stating the existence of a thing; they involve action. We need verbs.</p> <p>user=&gt; inc</p>"},{"location":"reference/basic-syntax/#_1","title":"<p>This is a verb called inc\u2013short for \u201cincrement\u201d. Specifically, inc is a symbol which points to a verb: #\u2013 just like the word \u201crun\u201d is a name for the concept of running. <p>There\u2019s a key distinction here\u2013that a signifier, a reference, a label, is not the same as the signified, the referent, the concept itself. If you write the word \u201crun\u201d on paper, the ink means nothing by itself. It\u2019s just a symbol. But in the mind of a reader, that symbol takes on meaning; the idea of running.</p> <p>Unlike the number 0, or the string \u201chi\u201d, symbols are references to other values. when Clojure evaluates a symbol, it looks up that symbol\u2019s meaning. Look up inc, and you get #. <p>Can we refer to the symbol itself, without looking up its meaning?</p> <p>user=&gt; 'inc inc Yes. The single quote ' escapes a sentence. In programming languages, we call sentences expressions or statements. A quote says \u201cRather than evaluating this expression\u2019s text, simply return the text itself, unchanged.\u201d Quote a symbol, get a symbol. Quote a number, get a number. Quote anything, and get it back exactly as it came in.</p> <p>user=&gt; '123 123 user=&gt; '\"foo\" \"foo\" user=&gt; '(1 2 3) (1 2 3) A new kind of value, surrounded by parentheses: the list. LISP originally stood for LISt Processing, and lists are still at the core of the language. In fact, they form the most basic way to compose expressions, or sentences. A list is a single expression which has multiple parts. For instance, this list contains three elements: the numbers 1, 2, and 3. Lists can contain anything: numbers, strings, even other lists:</p> <p>user=&gt; '(nil \"hi\") (nil \"hi\") A list containing two elements: the number 1, and a second list. That list contains two elements: the number 2, and another list. That list contains two elements: 3, and an empty list.</p> <p>user=&gt; '(1 (2 (3 ()))) (1 (2 (3 ()))) You could think of this structure as a tree\u2013which is a provocative idea, because languages are like trees too: sentences are comprised of clauses, which can be nested, and each clause may have subjects modified by adjectives, and verbs modified by adverbs, and so on. \u201cLindsay, my best friend, took the dog which we found together at the pound on fourth street, for a walk with her mother Michelle.\u201d</p> <p>Took   Lindsay     my best friend   the dog     which we found together       at the pound         on fourth street     for a walk       with her mother         Michelle But let\u2019s try something simpler. Something we know how to talk about. \u201cIncrement the number zero.\u201d As a tree:</p> <p>Increment   the number zero We have a symbol for incrementing, and we know how to write the number zero. Let\u2019s combine them in a list:</p> <p>clj=&gt; '(inc 0) (inc 0) A basic sentence. Remember, since it\u2019s quoted, we\u2019re talking about the tree, the text, the expression, by itself. Absent interpretation. If we remove the single-quote, Clojure will interpret the expression:</p> <p>user=&gt; (inc 0) 1 Incrementing zero yields one. And if we wanted to increment that value?</p> <p>Increment   increment     the number zero user=&gt; (inc (inc 0)) 2 A sentence in Lisp is a list. It starts with a verb, and is followed by zero or more objects for that verb to act on. Each part of the list can itself be another list, in which case that nested list is evaluated first, just like a nested clause in a sentence. When we type</p> <p>(inc (inc 0)) Clojure first looks up the meanings for the symbols in the code:</p> <p>(#   (#     0)) Then evaluates the innermost list (inc 0), which becomes the number 1: <p>(#  1) Finally, it evaluates the outer list, incrementing the number 1: <p>2 Every list starts with a verb. Parts of a list are evaluated from left to right. Innermost lists are evaluated before outer lists.</p> <p>(+ 1 (- 5 2) (+ 3 4)) (+ 1 3       (+ 3 4)) (+ 1 3       7) 11 That\u2019s it.</p> <p>The entire grammar of Lisp: the structure for every expression in the language. We transform expressions by substituting meanings for symbols, and obtain some result. This is the core of the Lambda Calculus, and it is the theoretical basis for almost all computer languages. Ruby, Javascript, C, Haskell; all languages express the text of their programs in different ways, but internally all construct a tree of expressions. Lisp simply makes it explicit.</p>","text":""},{"location":"reference/books/","title":"Books &amp; Tutorials on Clojure","text":"<p>Here is a list of Clojure books, grouped by skill level.  There is also a book list on Clojure.org or via a search for Clojure on o'Reilly lists most of these books.</p>"},{"location":"reference/books/#for-clojure-beginners","title":"For Clojure beginners","text":"<ul> <li>Living Clojure, O'Reilly April 2015</li> <li>Clojure for the Brave and the True, NoStartch Press September 2015</li> <li>Clojurescript Unraveled - June 2016</li> <li>Clojure from the ground up</li> <li>Practicalli Clojure</li> <li>Practicalli Clojure WebApps</li> </ul>"},{"location":"reference/books/#reference","title":"Reference","text":"<ul> <li>Clojure Programming Cookbook, Packt August 2016</li> <li>Clojure Cookbook, O'Reilly March 2014 - hundreds of real-world problems and solutions, ranging from basic utilities to rich web services to heavy data processing</li> </ul>"},{"location":"reference/books/#intermediate-level","title":"Intermediate level","text":"<ul> <li>Web Development with Clojure, Pragmatic July 2016</li> <li>Mastering Clojure, Packt March 2016</li> <li>Clojure in Action, Manning December 2015</li> <li>Programming Clojure, Pragmatic October 2015</li> <li>Clojure Applied: From Practice to Practitioner, Pragmatic September 2015</li> <li>Joy of Clojure, Manning May 2014</li> <li>Clojure Programming, O'Reilly March 2012</li> </ul>"},{"location":"reference/books/#other-books","title":"Other books","text":"<ul> <li>Learning Clojurescript, Packt June 2016</li> <li>Professional Clojure, Wiley/Wrox May 2016</li> <li>Clojure for Java Developers, Packt February 2016</li> <li>Clojure for Finance, January 2016</li> <li>Clojure Recipes, Addison-Wesley October 2015</li> <li>Clojure for Data Science, Packt September 2015</li> <li>Clojure High Performance Programming, Packt September 2015</li> <li>Clojure Data Structures &amp; Algorithms, Packt August 2015</li> <li>Mastering Clojure Data Analysis, Packt</li> <li>Clojure Reactive Programming, Packt March 2015</li> <li>Clojure Web Development Essentials, Packt February 2015</li> <li>Clojure Data Analysis Cookbook, Packt January 2015</li> <li>Mastering Clojure Macros, Pragmatic August 2014</li> <li>Clojure for Machine Learning, Packt April 2014</li> <li>Clojure for Domain-specific Languages, Packt December 2013</li> <li>Clojurescript: Up and Running, O'Reilly October 2012</li> <li>Building Web Applications with Clojure, Packt April 2012</li> <li>Functional Programming Patterns in Scala and Clojure, Pragmatic August 2014</li> </ul>"},{"location":"reference/changing-state/","title":"Changing State","text":""},{"location":"reference/code-analysis/","title":"Code Analysis","text":"<p>clj-kondo is a lint tool that highlights syntactic errors and suggests idioms for Clojure, ClojureScript and EDN.</p> <p>Use clj-kondo with your preferred editor to warning about errors as you type so issues can be fixed as soon as they occur, enhancing your joy of Clojure.</p> <p>clj-kondo can also be used as a command line tool for checking projects in development environments and continuous integration service, such as the setup-clojure GitHub action.</p> <p>Clojure LSP includes clj-kondo</p> <p>Clojure LSP install includes clj-kondo, removing the need for a separate install of clj-kondo</p>"},{"location":"reference/code-analysis/#install","title":"Install","text":"<p>Follow the clj-kondo install guide for your operating system.</p> <p>Clj-kondo config contains additional configuration for using clj-kondo with libraries that extend the Clojure language via macros.</p> SpacemacsDoom EmacsNeovim <p></p> <p>clj-kondo can be used if <code>cider</code> is configured as the clojure layer backend. If LSP is configured as the backend, should not be used as it may duplicate analysis results (e.g. doubling error and warning messgeas).</p> <p>Use Clojure LSP with Doom rather than clj-kondo by itself.</p> <p>Add the  <code>+lsp</code> feature to the Clojure module and enable the <code>lsp</code> module .config/doom/init.el<pre><code>(clojure +lsp)\nlsp\n</code></pre> Add the respective LSP server implementation to the operating system</p> <p>Practicalli Neovim provides a guide to configure Neovim with Treesitter as an LSP client, as well as a fennel based configuration for Neovim.</p>"},{"location":"reference/code-analysis/#command-line-analysis","title":"Command Line analysis","text":"<p>Run <code>clj-kondo</code> with the --lint option and specify a file or path</p> <p>To analyse a specific file</p> <pre><code>clj-kondon --lint ~/.config/deps.edn\n</code></pre> <p>Analyse a project, running the clj-kondo command from the root of the project</p> <pre><code>clj-kondon --lint .\n</code></pre>"},{"location":"reference/code-analysis/#clj-kondo-with-github-actions","title":"clj-kondo with GitHub actions","text":"<p>Add clj-kondo linting to continuous integration workflow.</p> <p></p>"},{"location":"reference/control-flow/","title":"Control Flow","text":""},{"location":"reference/core-async/","title":"Core.async","text":""},{"location":"reference/doc-and-source-functions/","title":"Doc and source functions","text":""},{"location":"reference/doc-and-source-functions/#the-doc-source-functions","title":"The doc &amp; source functions","text":"<p>If you are not using a Clojure aware editor or spend a lot of time in the REPL you can also view the documentation of a function by calling the <code>doc</code> function and see the source by calling the <code>source</code> function.</p> <p>To use the <code>doc</code> &amp; <code>source</code> functions in the REPL you should be in the <code>user</code> namespace.</p> <p>Note On the command line, start a REPL with the command <code>lein repl</code> and then view the documentation for three common functions used in clojure</p> <p>Make sure you are in the <code>user</code> namespace before calling the <code>doc</code> function.  If you are in another namespace, either change back using <code>(ns 'user)</code> or see the next section on using these functions in another namespace.</p> <pre><code>(doc doc)\n(doc map)\n(doc filter)\n(doc cons)\n\n(source doc)\n(source map)\n</code></pre> <p>Here is the doc string for <code>doc</code></p> <p></p> <p>Here is the source code for the <code>source</code> function</p> <p></p> <p>Hint As the documentation for a function is part of its definition, by looking at the source of a function you also get the documentation.</p>"},{"location":"reference/doc-and-source-functions/#using-doc-source-function-from-another-namespace","title":"Using doc &amp; source function from another namespace","text":"<p>The <code>doc</code> and <code>source</code> functions are only included in the <code>user</code> namespace. If you switch to another namespace or your editor places you in the current namespace of your project, these functions will not be available unless you including <code>core.repl</code> in the current namespace.</p> <p>From the REPL, evaluate the expression:</p> <pre><code>(use 'clojure.repl)\n</code></pre> <p>You could also <code>require</code> the <code>clojure.repl</code> library in your own code, however if you have a good editor it should provide these features without including this library.  Therefore the following code is shown only as an example and not a recommended approach.</p> <pre><code>(ns foobar\n(:require [clojure.repl :refer :all]))\n</code></pre>"},{"location":"reference/kebab-case/","title":"Clojure names use kebab-case","text":"<p>kebab-case is a clean, human-readable way to combine the words that would otherwise have spaces.</p> <p>Cloure uses kebab-case to combines words with a dash, <code>-</code>, rather than a space. e.g. <code>rock-paper-scissors</code>,  <code>tic-tac-toe</code> or <code>(def db-spec-development {:db-type \"h2\" :db-name \"banking-on-clojure\"})</code></p> <p>kebab-case is used throughout Clojure, including</p> <ul> <li>Var names with <code>def</code> and function names with <code>defn</code></li> <li>Local names with <code>let</code></li> <li>Clojure spec names</li> </ul> <p>kebab-case is used in lisp languages including Clojure. The style is also used in website URLs, e.g. practicalli.github.io/clojure-webapps</p>"},{"location":"reference/kebab-case/#using-meaningful-names","title":"Using meaningful names","text":"<p>To provide greater clarity to human developers, words may be combined for the names used when writing the code. Using multiple words can give greater context in to the purpose of that code.</p> <p>Using a combination of meaningful names makes understanding and debugging code far easier.</p>"},{"location":"reference/kebab-case/#spaces-characters-have-special-meaning","title":"Spaces characters have special meaning","text":"<p>Programming languages remove spaces between words because the space character is used as a separator when parsing the code.</p> <p>If spaces were not used as a separator for the some other character would be required, adding complexity to the language syntax.</p>"},{"location":"reference/kebab-case/#other-styles","title":"Other Styles","text":"<ul> <li>camelCase - used in Java and C-style programming languages</li> <li>PascalCase - used in the Pascal programming language</li> <li>snake_case - used for <code>ENVIRONMENT_VARIABLES</code> and <code>database_table_names_and_columns</code></li> </ul>"},{"location":"reference/naming-conventions/","title":"Naming Conventions","text":""},{"location":"reference/naming-conventions/#kebab-case","title":"Kebab-case","text":"<p>Kebab-case is the naming convention for all Clojure function names than contain more than one word.  Its name comes from the Shish Kebab style of cooking, where the words are the tofu and vegetables and the dashes are the skewers.</p> <pre><code>clj-time\nstring-parser\ndisplay-name\n</code></pre>"},{"location":"reference/naming-conventions/#predicates","title":"Predicates","text":"<p>Examples of predicate naming conventions from <code>clojure.core</code></p> <pre><code>contains?\nempty?\nevery?\nnot-empty?\nnull?\n</code></pre>"},{"location":"reference/naming-conventions/#namespace-requires-and-aliases","title":"Namespace requires and aliases","text":"<p>Required libraries should be given a contextually meaningful name as an alias, helping to identify the purpose of functions defined outside of the namespace.</p> <p>Giving meaningful context helps code to be understood by any person reading the code.  It is also easier to search for usage of functions from that context in the current project.</p> <p>Aliases are rarely typed more than once in full as Clojure editors have auto-complete, so there is no benefit to short of single character aliases.</p> <pre><code>(ns status-monitor.handler\n  (:require [hiccup.page :refer :as web-page]\n            [hiccup.form :refer :as web-form]))\n</code></pre> <p>In very commonly used libraries or very highly used functions through out the code, refer those functions explicitly</p> <pre><code>(ns naming.is.hard\n  (:require [compojure.core :refer [defroutes GET POST]]\n            [ring.middleware.defaults :refer [wrap-defaults site-defaults]]))\n</code></pre>"},{"location":"reference/naming-conventions/#converting-functions","title":"Converting functions","text":"<p>When a function takes values in one format or type and converts them to another</p> <p>Examples</p> <pre><code>md-&gt;html\n\nmap-&gt;Record-name  ; map factory function of a record -- creates a new record from a map\n-&gt;Record-name     ; positional factory function of a record -- creates a new record from a list of values\n</code></pre>"},{"location":"reference/naming/","title":"Naming","text":""},{"location":"reference/prasmatic-schema/","title":"Prasmatic Schema","text":""},{"location":"reference/reader-macros/","title":"Reader Macros","text":"<p>This is a collection of reader macros (think syntactic sugar) that are valid in Clojure.  These macros are useful for commenting out expressions, defining sets, ...</p> <p>Many reader macros start with the character #, which is in fact the Dispatch macro that tells the Clojure reader (the thing that takes a file of Clojure text and parses it for consumption in the compiler) to go and look at another read table for the definition of the next character - in essence this allows extending default reader behaviour.</p> <ul> <li> <p>#_ - Discard macro - ignore the next expression.  Often used to comment out code, especially when nested inside other expressions</p> </li> <li> <p>#' - Var macro - returns the reference to the var.  Used to pass the definition of something rather than the result of evaluating it.</p> </li> </ul> <p>There is a nice list of reader macros in the article: The weird and wonderful characters of Clojure by @kouphax.</p> <p>Hint Reader macros are part of the Clojure language specification, so are different to macros, which can be defined by anyone.</p>"},{"location":"reference/reader-macros/#todore-write","title":"Todo::Re-write","text":""},{"location":"reference/recursion/","title":"Recursion","text":"<p>Recursion is a highly valuable tool in functional programming as it provides an idiomatic way of processing collections of data.</p>"},{"location":"reference/recursion/#normal-recursion-is-more-idiomatic","title":"normal recursion is more idiomatic","text":"<p>On average it tends to give you clearer, more functional code whereas loop/recur tens to push you more towards an imperative, iterative style.</p>"},{"location":"reference/recursion/#recursive-functions","title":"Recursive functions","text":""},{"location":"reference/recursion/#warningrecursion-can-hit-the-limit-of-your-heapstack-and-cause-a-exception","title":"Warning::Recursion can hit the limit of your heap/stack and cause a ... exception","text":""},{"location":"reference/recursion/#tail-call-optimisation-with-recur","title":"Tail-call Optimisation with <code>recur</code>","text":"<p>Tail-call optimisation is where a part of memory is over-written by additional calls during recursive calls.  By using the same memory segment each time, then the memory footprint of your code does not increase.</p> <p>Therefore <code>recur</code> is good choice for deeply nested recursion or when manipulating larger (non-lazy) data structures.</p> <p>Without tail-call optimisation the code may otherwise cause a StackOverflow / Heap out of memory Error</p>"},{"location":"reference/recursion/#info","title":"Info::","text":"<p>Using the <code>recur</code> function as the last line of a <code>loop</code> or function will enable tail call optimisation.</p>"},{"location":"reference/recursion/#fast","title":"Fast","text":"<p>Using <code>loop</code> and <code>recur</code> it's one of the most efficient constructs in Clojure, match the speed of an equivalent for loop in Java code.</p>"},{"location":"reference/recursion/#restrictions","title":"Restrictions","text":"<p>you can only recur in tail position, you can't do mutual recursion between two different function etc.</p> <p>Sometime it simply isn't possible to use loop/recur or it may require the contort of code to something very unmanageable to do so.</p>"},{"location":"reference/recursion/#hintuse-recur-once-you-have-created-a-new-recursive-function","title":"Hint::Use recur once you have created a new recursive function","text":"<p>By calling a recursive function by name rather than using <code>recur</code> can prevent your code from remaining in an infinite loop if you get a terminating condition wrong.  Without recur you memory space will be eaten up and your code will stop. Once your function is working correctly, then you can replace the call to itself with <code>recur</code>.</p>"},{"location":"reference/recursion/#examples","title":"Examples","text":"<p>Here are two examples using two different recursion approaches. What are the guidelines of usage of one over another?</p> <p>This example recursively calls itself</p> <pre><code>(defn take-while\n  \"Returns a lazy sequence of successive items from coll while\n  (pred item) returns true. pred must be free of side-effects.\"\n  {:added \"1.0\"\n   :static true}\n  [pred coll]\n  (lazy-seq\n   (when-let [s (seq coll)]\n       (when (pred (first s))\n         (cons (first s) (take-while pred (rest s)))))))\n</code></pre> <p>This example uses <code>loop</code> and <code>recur</code> for recursively processing the collection.</p> <pre><code>(defn take-last\n  \"Returns a seq of the last n items in coll.  Depending on the type\n  of coll may be no better than linear time.  For vectors, see also subvec.\"\n  {:added \"1.1\"\n   :static true}\n  [n coll]\n  (loop [s (seq coll), lead (seq (drop n coll))]\n    (if lead\n      (recur (next s) (next lead))\n      s)))\n</code></pre>"},{"location":"reference/recursion/#hint","title":"Hint::","text":"<p>The above example could not use <code>recur</code> instead of the recursive call to <code>take-while</code> as that call is not in the last position. The <code>cons</code> function is in the last position of this function.</p>"},{"location":"reference/recursion/#misc","title":"Misc","text":"<p>The only one reason to use lazy-seq/lazy-cons mechanism is generating lazy sequences. If you don't need them then loop/recur should undoubtedly be used.</p>"},{"location":"reference/sequences/","title":"Reference: Clojure from the ground up: sequences","text":"<p>In Chapter 3, we discovered functions as a way to abstract expressions; to rephrase a particular computation with some parts missing. We used functions to transform a single value. But what if we want to apply a function to more than one value at once? What about sequences?</p> <p>For example, we know that (inc 2) increments the number 2. What if we wanted to increment every number in the vector [1 2 3], producing [2 3 4]?</p> <p>user=&gt; (inc [1 2 3]) ClassCastException clojure.lang.PersistentVector cannot be cast to java.lang.Number  clojure.lang.Numbers.inc (Numbers.java:110) Clearly inc can only work on numbers, not on vectors. We need a different kind of tool.</p> <p>A direct approach Let\u2019s think about the problem in concrete terms. We want to increment each of three elements: the first, second, and third. We know how to get an element from a sequence by using nth, so let\u2019s start with the first number, at index 0:</p> <p>user=&gt; (def numbers [1 2 3])</p>"},{"location":"reference/sequences/#usernumbers","title":"'user/numbers","text":"<p>user=&gt; (nth numbers 0) 1 user=&gt; (inc (nth numbers 0)) 2 So there\u2019s the first element incremented. Now we can do the second:</p> <p>user=&gt; (inc (nth numbers 1)) 3 user=&gt; (inc (nth numbers 2)) 4 And it should be straightforward to combine these into a vector\u2026</p> <p>user=&gt; [(inc (nth numbers 0)) (inc (nth numbers 1)) (inc (nth numbers 2))] [2 3 4] Success! We\u2019ve incremented each of the numbers in the list! How about a list with only two elements?</p> <p>user=&gt; (def numbers [1 2])</p>"},{"location":"reference/sequences/#usernumbers_1","title":"'user/numbers","text":"<p>user=&gt; [(inc (nth numbers 0)) (inc (nth numbers 1)) (inc (nth numbers 2))]</p> <p>IndexOutOfBoundsException   clojure.lang.PersistentVector.arrayFor (PersistentVector.java:107) Shoot. We tried to get the element at index 2, but couldn\u2019t, because numbers only has indices 0 and 1. Clojure calls that \u201cindex out of bounds\u201d.</p> <p>We could just leave off the third expression in the vector; taking only elements 0 and 1. But the problem actually gets much worse, because we\u2019d need to make this change every time we wanted to use a different sized vector. And what of a vector with 1000 elements? We\u2019d need 1000 (inc (nth numbers ...)) expressions! Down this path lies madness.</p> <p>Let\u2019s back up a bit, and try a slightly smaller problem.</p> <p>Recursion What if we just incremented the first number in the vector? How would that work? We know that first finds the first element in a sequence, and rest finds all the remaining ones.</p> <p>user=&gt; (first [1 2 3]) 1 user=&gt; (rest [1 2 3]) (2 3) So there\u2019s the pieces we\u2019d need. To glue them back together, we can use a function called cons, which says \u201cmake a list beginning with the first argument, followed by all the elements in the second argument\u201d.</p> <p>user=&gt; (cons 1 [2]) (1 2) user=&gt; (cons 1 [2 3]) (1 2 3) user=&gt; (cons 1 [2 3 4]) (1 2 3 4) OK so we can split up a sequence, increment the first part, and join them back together. Not so hard, right?</p> <p>(defn inc-first [numbers]   (cons (inc (first numbers))         (rest numbers))) user=&gt; (inc-first [1 2 3 4]) (2 2 3 4) Hey, there we go! First element changed. Will it work with any length list?</p> <p>user=&gt; (inc-first [5]) (6) user=&gt; (inc-first [])</p> <p>NullPointerException   clojure.lang.Numbers.ops (Numbers.java:942) Shoot. We can\u2019t increment the first element of this empty vector, because it doesn\u2019t have a first element.</p> <p>user=&gt; (first []) nil user=&gt; (inc nil)</p> <p>NullPointerException   clojure.lang.Numbers.ops (Numbers.java:942) So there are really two cases for this function. If there is a first element in numbers, we\u2019ll increment it as normal. If there\u2019s no such element, we\u2019ll return an empty list. To express this kind of conditional behavior, we\u2019ll use a Clojure special form called if:</p>"},{"location":"reference/sequences/#user-doc-if","title":"user=&gt; (doc if)","text":"<p>if   (if test then else?) Special Form   Evaluates test. If not the singular values nil or false,   evaluates and yields then, otherwise, evaluates and yields else. If   else is not supplied it defaults to nil.</p> <p>Please see http://clojure.org/special_forms#if To confirm our intuition:</p> <p>user=&gt; (if true :a :b) :a user=&gt; (if false :a :b) :b Seems straightforward enough.</p> <p>(defn inc-first [numbers]   (if (first numbers)     ; If there's a first number, build a new list with cons     (cons (inc (first numbers))           (rest numbers))     ; If there's no first number, just return an empty list     (list)))</p> <p>user=&gt; (inc-first []) () user=&gt; (inc-first [1 2 3]) (2 2 3) Success! Now we can handle both cases: empty sequences, and sequences with things in them. Now how about incrementing that second number? Let\u2019s stare at that code for a bit.</p> <p>(rest numbers) Hang on. That list\u2013(rest numbers)\u2013that\u2019s a list of numbers too. What if we\u2026 used our inc-first function on that list, to increment its first number? Then we\u2019d have incremented both the first and the second element.</p> <p>(defn inc-more [numbers]   (if (first numbers)     (cons (inc (first numbers))           (inc-more (rest numbers)))     (list))) user=&gt; (inc-more [1 2 3 4]) (2 3 4 5) Odd. That didn\u2019t just increment the first two numbers. It incremented all the numbers. We fell into the complete solution entirely by accident. What happened here?</p> <p>Well first we\u2026 yes, we got the number one, and incremented it. Then we stuck that onto (inc-first [2 3 4]), which got two, and incremented it. Then we stuck that two onto (inc-first [3 4]), which got three, and then we did the same for four. Only that time around, at the very end of the list, (rest [4]) would have been empty. So when we went to get the first number of the empty list, we took the second branch of the if, and returned the empty list.</p> <p>Having reached the bottom of the function calls, so to speak, we zip back up the chain. We can imagine this function turning into a long string of cons calls, like so:</p> <p>(cons 2 (cons 3 (cons 4 (cons 5 '())))) (cons 2 (cons 3 (cons 4 '(5)))) (cons 2 (cons 3 '(4 5))) (cons 2 '(3 4 5)) '(2 3 4 5) This technique is called recursion, and it is a fundamental principle in working with collections, sequences, trees, or graphs\u2026 any problem which has small parts linked together. There are two key elements in a recursive program:</p> <p>Some part of the problem which has a known solution A relationship which connects one part of the problem to the next Incrementing the elements of an empty list returns the empty list. This is our base case: the ground to build on. Our inductive case, also called the recurrence relation, is how we broke the problem up into incrementing the first number in the sequence, and incrementing all the numbers in the rest of the sequence. The if expression bound these two cases together into a single function; a function defined in terms of itself.</p> <p>Once the initial step has been taken, every step can be taken.</p> <p>user=&gt; (inc-more [1 2 3 4 5 6 7 8 9 10 11 12]) (2 3 4 5 6 7 8 9 10 11 12 13) This is the beauty of a recursive function; folding an unbounded stream of computation over and over, onto itself, until only a single step remains.</p> <p>Generalizing from inc We set out to increment every number in a vector, but nothing in our solution actually depended on inc. It just as well could have been dec, or str, or keyword. Let\u2019s parameterize our inc-more function to use any transformation of its elements:</p> <p>(defn transform-all [f xs]   (if (first xs)     (cons (f (first xs))           (transform-all f (rest xs)))     (list))) Because we could be talking about any kind of sequence, not just numbers, we\u2019ve named the sequence xs, and its first element x. We also take a function f as an argument, and that function will be applied to each x in turn. So not only can we increment numbers\u2026</p> <p>user=&gt; (transform-all inc [1 2 3 4]) (2 3 4 5) \u2026but we can turn strings to keywords\u2026</p> <p>user=&gt; (transform-all keyword [\"bell\" \"hooks\"]) (:bell :hooks) \u2026or wrap every element in a list:</p> <p>user=&gt; (transform-all list [:codex :book :manuscript]) ((:codex) (:book) (:manuscript)) In short, this function expresses a sequence in which each element is some function applied to the corresponding element in the underlying sequence. This idea is so important that it has its own name, in mathematics, Clojure, and other languages. We call it map.</p> <p>user=&gt; (map inc [1 2 3 4]) (2 3 4 5) You might remember maps as a datatype in Clojure, too\u2013they\u2019re dictionaries that relate keys to values.</p> <p>{:year  1969  :event \"moon landing\"} The function map relates one sequence to another. The type map relates keys to values. There is a deep symmetry between the two: maps are usually sparse, and the relationships between keys and values may be arbitrarily complex. The map function, on the other hand, usually expresses the same type of relationship, applied to a series of elements in fixed order.</p> <p>Building sequences Recursion can do more than just map. We can use it to expand a single value into a sequence of values, each related by some function. For instance:</p> <p>(defn expand [f x count]   (if (pos? count)     (cons x (expand f (f x) (dec count))))) Our base case is x itself, followed by the sequence beginning with (f x). That sequence in turn expands to (f (f x)), and then (f (f (f x))), and so on. Each time we call expand, we count down by one using dec. Once the count is zero, the if returns nil, and evaluation stops. If we start with the number 0 and use inc as our function:</p> <p>user=&gt; user=&gt; (expand inc 0 10) (0 1 2 3 4 5 6 7 8 9) Clojure has a more general form of this function, called iterate.</p> <p>user=&gt; (take 10 (iterate inc 0)) (0 1 2 3 4 5 6 7 8 9) Since this sequence is infinitely long, we\u2019re using take to select only the first 10 elements. We can construct more complex sequences by using more complex functions:</p> <p>user=&gt; (take 10 (iterate (fn [x] (if (odd? x) (+ 1 x) (/ x 2))) 10)) (10 5 6 3 4 2 1 2 1 2) Or build up strings:</p> <p>user=&gt; (take 5 (iterate (fn [x] (str x \"o\")) \"y\")) (\"y\" \"yo\" \"yoo\" \"yooo\" \"yoooo\") iterate is extremely handy for working with infinite sequences, and has some partners in crime. repeat, for instance, constructs a sequence where every element is the same.</p> <p>user=&gt; (take 10 (repeat :hi)) (:hi :hi :hi :hi :hi :hi :hi :hi :hi :hi) user=&gt; (repeat 3 :echo) (:echo :echo :echo) And its close relative repeatedly simply calls a function (f) to generate an infinite sequence of values, over and over again, without any relationship between elements. For an infinite sequence of random numbers:</p> <p>user=&gt; (rand) 0.9002678382322784 user=&gt; (rand) 0.12375594203332863 user=&gt; (take 3 (repeatedly rand)) (0.44442397843046755 0.33668691162169784 0.18244875487846746) Notice that calling (rand) returns a different number each time. We say that rand is an impure function, because it cannot simply be replaced by the same value every time. It does something different each time it\u2019s called.</p> <p>There\u2019s another very handy sequence function specifically for numbers: range, which generates a sequence of numbers between two points. (range n) gives n successive integers starting at 0. (range n m) returns integers from n to m-1. (range n m step) returns integers from n to m, but separated by step.</p> <p>user=&gt; (range 5) (0 1 2 3 4) user=&gt; (range 2 10) (2 3 4 5 6 7 8 9) user=&gt; (range 0 100 5) (0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95) To extend a sequence by repeating it forever, use cycle:</p> <p>user=&gt; (take 10 (cycle [1 2 3])) (1 2 3 1 2 3 1 2 3 1) Transforming sequences Given a sequence, we often want to find a related sequence. map, for instance, applies a function to each element\u2013but has a few more tricks up its sleeve.</p> <p>user=&gt; (map (fn [n vehicle] (str \"I've got \" n \" \" vehicle \"s\"))          [0 200 9]          [\"car\" \"train\" \"kiteboard\"]) (\"I've got 0 cars\" \"I've got 200 trains\" \"I've got 9 kiteboards\") If given multiple sequences, map calls its function with one element from each sequence in turn. So the first value will be (f 0 \"car\"), the second (f 200 \"train\"), and so on. Like a zipper, map folds together corresponding elements from multiple collections. To sum three vectors, column-wise:</p> <p>user=&gt; (map + [1 2 3]               [4 5 6]               [7 8 9]) (12 15 18) If one sequence is bigger than another, map stops at the end of the smaller one. We can exploit this to combine finite and infinite sequences. For example, to number the elements in a vector:</p> <p>user=&gt; (map (fn [index element] (str index \". \" element))             (iterate inc 0)             [\"erlang\" \"ruby\" \"haskell\"]) (\"0. erlang\" \"1. ruby\" \"2. haskell\") Transforming elements together with their indices is so common that Clojure has a special function for it: map-indexed:</p> <p>user=&gt; (map-indexed (fn [index element] (str index \". \" element))                     [\"erlang\" \"ruby\" \"haskell\"]) (\"0. erlang\" \"1. ruby\" \"2. haskell\") You can also tack one sequence onto the end of another, like so:</p> <p>user=&gt; (concat [1 2 3] [:a :b :c] [4 5 6]) (1 2 3 :a :b :c 4 5 6) Another way to combine two sequences is to riffle them together, using interleave.</p> <p>user=&gt; (interleave [:a :b :c] [1 2 3]) (:a 1 :b 2 :c 3) And if you want to insert a specific element between each successive pair in a sequence, try interpose:</p> <p>user=&gt; (interpose :and [1 2 3 4]) (1 :and 2 :and 3 :and 4) To reverse a sequence, use reverse.</p> <p>user=&gt; (reverse [1 2 3]) (3 2 1) user=&gt; (reverse \"woolf\") (\\f \\l \\o \\o \\w) Strings are sequences too! Each element of a string is a character, written \\f. You can rejoin those characters into a string with apply str:</p> <p>user=&gt; (apply str (reverse \"woolf\")) \"floow\" \u2026and break strings up into sequences of chars with seq.</p> <p>user=&gt; (seq \"sato\") (\\s \\a \\t \\o) To randomize the order of a sequence, use shuffle.</p> <p>user=&gt; (shuffle [1 2 3 4]) [3 1 2 4] user=&gt; (apply str (shuffle (seq \"abracadabra\"))) \"acaadabrrab\" Subsequences We\u2019ve already seen take, which selects the first n elements. There\u2019s also drop, which removes the first n elements.</p> <p>user=&gt; (range 10) (0 1 2 3 4 5 6 7 8 9) user=&gt; (take 3 (range 10)) (0 1 2) user=&gt; (drop 3 (range 10)) (3 4 5 6 7 8 9) And for slicing apart the other end of the sequence, we have take-last and drop-last:</p> <p>user=&gt; (take-last 3 (range 10)) (7 8 9) user=&gt; (drop-last 3 (range 10)) (0 1 2 3 4 5 6) take-while and drop-while work just like take and drop, but use a function to decide when to cut.</p> <p>user=&gt; (take-while pos? [3 2 1 0 -1 -2 10]) (3 2 1) In general, one can cut a sequence in twain by using split-at, and giving it a particular index. There\u2019s also split-with, which uses a function to decide when to cut.</p> <p>(split-at 4 (range 10)) [(0 1 2 3) (4 5 6 7 8 9)] user=&gt; (split-with number? [1 2 3 :mark 4 5 6 :mark 7]) [(1 2 3) (:mark 4 5 6 :mark 7)] Notice that because indexes start at zero, sequence functions tend to have predictable numbers of elements. (split-at 4) yields four elements in the first collection, and ensures the second collection begins at index four. (range 10) has ten elements, corresponding to the first ten indices in a sequence. (range 3 5) has two (since 5 - 3 is two) elements. These choices simplify the definition of recursive functions as well.</p> <p>We can select particular elements from a sequence by applying a function. To find all positive numbers in a list, use filter:</p> <p>user=&gt; (filter pos? [1 5 -4 -7 3 0]) (1 5 3) filter looks at each element in turn, and includes it in the resulting sequence only if (f element) returns a truthy value. Its complement is remove, which only includes those elements where (f element) is false or nil.</p> <p>user=&gt; (remove string? [1 \"turing\" :apple]) (1 :apple) Finally, one can group a sequence into chunks using partition, partition-all, or partition-by. For instance, one might group alternating values into pairs:</p> <p>user=&gt; (partition 2 [:cats 5 :bats 27 :crocodiles 0]) ((:cats 5) (:bats 27) (:crocodiles 0)) Or separate a series of numbers into negative and positive runs:</p> <p>(user=&gt; (partition-by neg? [1 2 3 2 1 -1 -2 -3 -2 -1 1 2]) ((1 2 3 2 1) (-1 -2 -3 -2 -1) (1 2)) Collapsing sequences After transforming a sequence, we often want to collapse it in some way; to derive some smaller value. For instance, we might want the number of times each element appears in a sequence:</p> <p>user=&gt; (frequencies [:meow :mrrrow :meow :meow]) {:meow 3, :mrrrow 1} Or to group elements by some function:</p> <p>user=&gt; (pprint (group-by :first [{:first \"Li\"    :last \"Zhou\"}                                  {:first \"Sarah\" :last \"Lee\"}                                  {:first \"Sarah\" :last \"Dunn\"}                                  {:first \"Li\"    :last \"O'Toole\"}])) {\"Li\"    [{:last \"Zhou\", :first \"Li\"}   {:last \"O'Toole\", :first \"Li\"}],  \"Sarah\" [{:last \"Lee\", :first \"Sarah\"} {:last \"Dunn\", :first \"Sarah\"}]} Here we\u2019ve taken a sequence of people with first and last names, and used the :first keyword (which can act as a function!) to look up those first names. group-by used that function to produce a map of first names to lists of people\u2013kind of like an index.</p> <p>In general, we want to combine elements together in some way, using a function. Where map treated each element independently, reducing a sequence requires that we bring some information along. The most general way to collapse a sequence is reduce.</p>"},{"location":"reference/sequences/#user-doc-reduce","title":"user=&gt; (doc reduce)","text":"<p>clojure.core/reduce ([f coll] [f val coll])   f should be a function of 2 arguments. If val is not supplied,   returns the result of applying f to the first 2 items in coll, then   applying f to that result and the 3rd item, etc. If coll contains no   items, f must accept no arguments as well, and reduce returns the   result of calling f with no arguments.  If coll has only 1 item, it   is returned and f is not called.  If val is supplied, returns the   result of applying f to val and the first item in coll, then   applying f to that result and the 2nd item, etc. If coll contains no   items, returns val and f is not called. That\u2019s a little complicated, so we\u2019ll start small. We need a function, f, which combines successive elements of the sequence. (f state element) will return the state for the next invocation of f. As f moves along the sequence, it carries some changing state with it. The final state is the return value of reduce.</p> <p>user=&gt; (reduce + [1 2 3 4]) 10 reduce begins by calling (+ 1 2), which yields the state 3. Then it calls (+ 3 3), which yields 6. Then (+ 6 4), which returns 10. We\u2019ve taken a function over two elements, and used it to combine all the elements. Mathematically, we could write:</p> <p>1 + 2 + 3 + 4     3 + 3 + 4         6 + 4            10 So another way to look at reduce is like sticking a function between each pair of elements. To see the reducing process in action, we can use reductions, which returns a sequence of all the intermediate states.</p> <p>user=&gt; (reductions + [1 2 3 4]) (1 3 6 10) Oftentimes we include a default state to start with. For instance, we could start with an empty set, and add each element to it as we go along:</p> <p>user=&gt; (reduce conj #{} [:a :b :b :b :a :a])</p>"},{"location":"reference/sequences/#a-b","title":"{:a :b}","text":"<p>Reducing elements into a collection has its own name: into. We can conj [key value] vectors into a map, for instance, or build up a list:</p> <p>user=&gt; (into {} [[:a 2] [:b 3]]) {:a 2, :b 3} user=&gt; (into (list) [1 2 3 4]) (4 3 2 1) Because elements added to a list appear at the beginning, not the end, this expression reverses the sequence. Vectors conj onto the end, so to emit the elements in order, using reduce, we might try:</p> <p>user=&gt; (reduce conj [] [1 2 3 4 5]) (reduce conj [] [1 2 3 4 5]) [1 2 3 4 5] Which brings up an interesting thought: this looks an awful lot like map. All that\u2019s missing is some kind of transformation applied to each element.</p> <p>(defn my-map [f coll]   (reduce (fn [output element]             (conj output (f element)))           []           coll)) user=&gt; (my-map inc [1 2 3 4]) [2 3 4 5] Huh. map is just a special kind of reduce. What about, say, take-while?</p> <p>(defn my-take-while [f coll]   (reduce (fn [out elem]             (if (f elem)               (conj out elem)               (reduced out)))           []           coll)) We\u2019re using a special function here, reduced, to indicate that we\u2019ve completed our reduction early and can skip the rest of the sequence.</p> <p>user=&gt; (my-take-while pos? [2 1 0 -1 0 1 2]) [2 1] reduce really is the uber function over sequences. Almost any operation on a sequence can be expressed in terms of a reduce\u2013though for various reasons, many of the Clojure sequence functions are not written this way. For instance, take-while is actually defined like so:</p> <p>user=&gt; (source take-while) (defn take-while   \"Returns a lazy sequence of successive items from coll while   (pred item) returns true. pred must be free of side-effects.\"   {:added \"1.0\"    :static true}   [pred coll]   (lazy-seq    (when-let [s (seq coll)]        (when (pred (first s))          (cons (first s) (take-while pred (rest s))))))) There\u2019s a few new pieces here, but the structure is essentially the same as our initial attempt at writing map. When the predicate matches the first element, cons the first element onto take-while, applied to the rest of the sequence. That lazy-seq construct allows Clojure to compute this sequence as required, instead of right away. It defers execution to a later time.</p> <p>Most of Clojure\u2019s sequence functions are lazy. They don\u2019t do anything until needed. For instance, we can increment every number from zero to infinity:</p> <p>user=&gt; (def infinite-sequence (map inc (iterate inc 0)))</p>"},{"location":"reference/sequences/#userinfinite-sequence","title":"'user/infinite-sequence","text":"<p>user=&gt; (realized? infinite-sequence) false That function returned immediately. Because it hasn\u2019t done any work yet, we say the sequence is unrealized. It doesn\u2019t increment any numbers at all until we ask for them:</p> <p>user=&gt; (take 10 infinite-sequence) (1 2 3 4 5 6 7 8 9 10) user=&gt; (realized? infinite-sequence) true Lazy sequences also remember their contents, once evaluated, for faster access.</p> <p>Putting it all together We\u2019ve seen how recursion generalizes a function over one thing into a function over many things, and discovered a rich landscape of recursive functions over sequences. Now let\u2019s use our knowledge of sequences to solve a more complex problem: find the sum of the products of consecutive pairs of the first 1000 odd integers.</p> <p>First, we\u2019ll need the integers. We can start with 0, and work our way up to infinity. To save time printing an infinite number of integers, we\u2019ll start with just the first 10.</p> <p>user=&gt; (take 10 (iterate inc 0)) (0 1 2 3 4 5 6 7 8 9) Now we need to find only the ones which are odd. Remember, filter pares down a sequence to only those elements which pass a test.</p> <p>user=&gt; (take 10 (filter odd? (iterate inc 0))) (1 3 5 7 9 11 13 15 17 19) For consecutive pairs, we want to take [1 3 5 7 ...] and find a sequence like ([1 3] [3 5] [5 7] ...). That sounds like a job for partition:</p> <p>user=&gt; (take 3 (partition 2 (filter odd? (iterate inc 0)))) ((1 3) (5 7) (9 11)) Not quite right\u2013this gave us non-overlapping pairs, but we wanted overlapping ones too. A quick check of (doc partition) reveals the step parameter:</p> <p>user=&gt; (take 3 (partition 2 1 (filter odd? (iterate inc 0)))) ((1 3) (3 5) (5 7)) Now we need to find the product for each pair. Given a pair, multiply the two pieces together\u2026 yes, that sounds like map:</p> <p>user=&gt; (take 3 (map (fn [pair] (* (first pair) (second pair)))                     (partition 2 1 (filter odd? (iterate inc 0))))) (3 15 35) Getting a bit unwieldy, isn\u2019t it? Only one final step: sum all those products. We\u2019ll adjust the take to include the first 1000, not the first 3, elements.</p> <p>user=&gt; (reduce +                (take 1000                      (map (fn [pair] (* (first pair) (second pair)))                           (partition 2 1                                     (filter odd?                                             (iterate inc 0))))) 1335333000 The sum of the first thousand products of consecutive pairs of the odd integers starting at 0. See how each part leads to the next? This expression looks a lot like the way we phrased the problem in English\u2013but both English and Lisp expressions are sort of backwards, in a way. The part that happens first appears deepest, last, in the expression. In a chain of reasoning like this, it\u2019d be nicer to write it in order.</p> <p>user=&gt; (-&gt;&gt; 0             (iterate inc)             (filter odd?)             (partition 2 1)             (map (fn [pair]                    (* (first pair) (second pair))))             (take 1000)             (reduce +)) 1335333000 Much easier to read: now everything flows in order, from top to bottom, and we\u2019ve flattened out the deeply nested expressions into a single level. This is how object-oriented languages structure their expressions: as a chain of function invocations, each acting on the previous value.</p> <p>But how is this possible? Which expression gets evaluated first? (take 1000) isn\u2019t even a valid call\u2013where\u2019s its second argument? How are any of these forms evaluated?</p> <p>What kind of arcane function is -&gt;&gt;?</p> <p>All these mysteries, and more, in Chapter 5: Macros.</p> <p>Problems Write a function to find out if a string is a palindrome\u2013that is, if it looks the same forwards and backwards. Find the number of \u2018c\u2019s in \u201cabracadabra\u201d. Write your own version of filter. Find the first 100 prime numbers: 2, 3, 5, 7, 11, 13, 17, \u2026.</p>"},{"location":"reference/threading-macros/","title":"Reference: Threading macros","text":"<p>Using the threading macro, the result of every function is passed onto the next function in the list.  This can be seen very clearly using ,,, to denote where the value is passed to the next function</p> <pre><code>(-&gt;\n \"project.clj\"\n slurp ,,,\n read-string ,,,\n (nth ,,, 2))\n</code></pre> <p>To make this really simple lets create a contrived example of the threading macro.  Here we use the <code>str</code> function to join strings together.  Each individual <code>str</code> function joins its own strings together, passing the resulting string as the first argument to the next function.</p> <pre><code>(-&gt;\n (str \"This\" \" \" \"is\" \" \")\n (str \"the\" \" \" \"threading\" \" \" \"macro\")\n (str \"in\" \" \" \"action.\"))\n</code></pre> <p>Output</p> <pre><code>;; =&gt; \"This is the threading macro in action\"\n</code></pre>"},{"location":"reference/threading-macros/#hintcommas-in-clojure-are-whitespace","title":"Hint::Commas in clojure are whitespace","text":"<p>Commas are simply ignored when the Clojure Reader parses code.  Commas are rarely used and only to help human readability of the code</p>"},{"location":"reference/threading-macros/#thread-last-macro","title":"Thread-last macro","text":"<p>Using the thread-last macro, -&gt;&gt;, the result of a function is passed as the last argument of the next function call.  So in another simple series of str function calls, our text comes out backwards.</p> <pre><code>(-&gt;&gt;  \" this\"\n (str \" is\")\n (str \" backwards\"))\n</code></pre>"},{"location":"reference/clojure-cli/","title":"Reference: Clojure CLI","text":"<p>A reference on using Clojure CLI and using community tools effectively.</p> <ul> <li>structure of the deps.edn configuration</li> <li>execution options</li> <li>Java Virtual Machine options</li> <li>defining custom aliases</li> <li>common aliases from practicalli/clojure-deps-edn project</li> </ul>"},{"location":"reference/clojure-cli/example-alias-definitions/","title":"Common alias definitions","text":""},{"location":"reference/clojure-cli/example-alias-definitions/#task-run-a-simple-terminal-repl","title":"Task: Run a simple terminal REPL","text":"<p><code>clojure</code> and <code>clj</code> (requires rlwrap) will run a REPL if given no other arguments.</p> <p>Running either command from the root directory of a project will merge the <code>deps.edn</code> configuration with <code>~/.clojure/deps.edn</code>.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-run-a-repl-with-additional-dependencies-and-paths","title":"Task: Run a REPL with additional dependencies and paths","text":"<p><code>clojure -M:alias</code> will run a repl if the alias does not contain a main namespace defined in <code>:main-opts</code>, e.g. <code>:main-opts [\"-m\" \"namespace.main\"]</code>.  The deps and path values are included from the alias.</p> <p>If the following alias is defined in the project <code>deps.edn</code> file</p> <pre><code>:env/dev\n{:extra-paths [\"resources\"]\n :extra-deps {com.h2database/h2 {:mvn/version \"1.4.200\"}}}\n</code></pre> <p><code>clojure -M:env/dev</code> will add <code>resources</code> directory to the path and the h2 database library to the dependencies, then runs a REPL.</p> <p>Including the <code>-r</code> option in the command line forces a REPL to run, even if a main namespace is provided via <code>:main-opts</code> or the command line.</p> <pre><code>clojure -r -M:alias1:alias2\n</code></pre> <p>The dependencies and paths will be merged from the alias from left to right, with each successive alias over-riding the value of any matching keys in the dependencies.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-create-a-new-project-from-template","title":"Task: Create a new project from template","text":"<p>The <code>clj-new</code> community tool can be used to create a Clojure / ClojureScript project, using a template to provide a project structure and example source code and tests.</p> <p>Using the <code>:main-opts</code> approach, an alias for <code>clj-new</code> would be defined as follows</p> <pre><code>  :project/new\n  {:extra-deps {seancorfield/clj-new {:mvn/version \"1.0.215\"}}\n   :main-opts  [\"-m\" \"clj-new.create\"]}\n</code></pre> <p>The <code>clj-new</code> tool can be run using the <code>-M</code> flag, passing the template and project names as arguments.</p> <p><code>clojure -M:project/new template-name project-domain/application-name</code></p> <p>To create a project as an application (to be run via the command line) for the practicalli domain with the application called banking-on-clojure</p> <pre><code>clojure -M:new app practicalli/banking-on-clojure\n</code></pre> <p>The latest version of the <code>clj-new</code> project also supports using the <code>-X</code> flag and default arguments.</p> <p>Adding the <code>:exec-fn</code> to the <code>clj-new</code> alias, the <code>-X</code> flag can be used instead of the <code>-M</code>.  Arguments are supplied as key/value pairs</p> <pre><code>  :project/new\n  {:extra-deps {seancorfield/clj-new {:mvn/version \"1.1.215\"}}\n   :exec-fn clj-new/create}\n</code></pre> <p>Use this alias with the <code>-X</code> flag</p> <pre><code>clojure -X:project/new :template template-name :name practicalli/banking-on-clojure\n</code></pre> <p>Default values can be added using the <code>:exec-args</code> key to the alias</p> <pre><code>:project/new\n{:extra-deps {seancorfield/clj-new {:mvn/version \"1.1.215\"}}\n :exec-fn clj-new.create\n :exec-args {:template lib :name practicalli/playground}}\n</code></pre> <p><code>clojure -M:project/new :name practicalli/awesome-webapp</code> will create a new project using the <code>{:template lib :name practicalli/awesome-webapp}</code> argument.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-specific-function","title":"Task: Executing a specific function","text":"<p>Clojure can run a specific function, useful for one off tasks or timed batch processing (via cron or similar tool) as well as complete applications.</p> <p>Arguments to the function are passed as a hash-map, defined in either an aliases <code>:exec-args</code> key or as key value pairs on the command line.  Command line key value pairs are merged with the <code>:exec-arg</code> hash-map, replacing the values from the command line if there are matching keys.</p> <p>Scenarios</p> <p><code>clojure -X namespace/fn</code> runs the function specified on the command line, passing an empty hash-map as an argument</p> <p><code>clojure -X:alias fn</code> runs the function if the <code>:ns-default</code> is set to the namespace that contains the function, otherwise \"Unqualified function can't be resolved: fn-name\" error is returned.</p> <p><code>clojure -X:alias</code> runs the function specified by <code>:exec-fn</code> in the alias.  The function must include its namespace or have that namespace defined in <code>:ns-default</code>. If <code>:exec-args</code> is defined in the alias, its value is passed to the function, otherwise an empty hash-map is passed to the function as an argument.</p> <p><code>clojure -X:alias namespace/fn</code> will run the function specified on the command line, over-riding <code>:exec-fn</code> if it is defined in the alias.  <code>:exec-args</code> will be passed to the command line function if defined in the alias. Dependencies and paths will be used from the alias. Assumption: the command line namespace also overrides the <code>:ns-default</code> value if set.</p> <p><code>clojure -X:alias :key1 val1 :key2 val2</code> will execute the function defined in <code>:exec-fn</code> and pass it the key value pairs from the command line as a hash map.  If the alias has <code>:exec-args</code> defined, command line args are merged into the <code>:exec-fn</code> hash-map, replacing the default values in <code>:exec-args</code> where keys match.</p> <p>Assuming there is an alias called <code>database/migrate</code> defined in the project <code>deps.edn</code></p> <pre><code>:database/migrate\n{:exec-fn practicalli.banking-on-clojure.database/migrate\n :exec-args {:db-type \"h2\" :database \"banking-on-clojure\"}}\n</code></pre> <p><code>clojure -X:database/migrate :database \"specs-repository\"</code> would merge the command line args with <code>:exec-args</code> to create the hash-map <code>{:db-type \"h2\" :database \"specs-repository\"}</code> which is passed to the <code>practicalli.banking-on-clojure.database/migrate</code> function as an argument.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-range-of-functions","title":"Task: Executing a range of functions","text":"<p><code>:ns-default</code> in an alias defines the namespace that contains the functions that could be executed.</p> <pre><code>{:aliases\n  {:project/run\n    {:ns-default practicalli/banking-on-clojure}}}\n</code></pre> <p>Specific functions from the namespace can be called via the command line</p> <pre><code>clojure -X:project/run migrate-db :db-type h2 :database banking-on-clojure\nclojure -X:project/run server-start :port 8080\n</code></pre>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-dry-run-or-prepare-for-ci-containers","title":"Task: Dry Run or Prepare for CI / Containers","text":"<p><code>clojure -P</code> will download the libraries defined in <code>:deps</code> in the project <code>deps.edn</code> and do nothing else.  Standard out shows downloading of dependencies not already cached locally, including name and versions and repository downloaded from.</p> <p></p> <p>Qualified namespaces required</p> <p>If an unqualified library name is used, e.g. <code>compojure</code>, then a warning is sent to the standard out.  Change the name of the library to be fully qualified e.g. <code>weavejester/compojure</code>.  Use the same name if there is no official qualified domain, e.g. <code>http-kit/http-kit</code></p> <p>The <code>-P</code> flag can be used to modify an existing command to ensure no execution takes place, ensuring a prepare only (dry run) action.</p> <p><code>clojure -P -M:alias-name</code> downloads the dependencies for the specific aliases and multiple aliases can be chained together, e.g. <code>clojure -P -M:dev/env:test-runner/kaocha</code></p> <p>The <code>-P</code> flag uses everything from an alias not related to execution.</p> <p>The classic way to download deps was to run <code>clojure -A:aliases -Spath</code>, where <code>-Spath</code> prevented execution of repl or main.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#run-a-clojure-application","title":"Run a Clojure application","text":"<p><code>clojure -m full.namespace.to.dash-main</code> calls the <code>-main</code> function from the given namespace. Arguments to the function are simply added to the end of the command line and passed to the <code>-main</code> function in the given namespace.</p> <p>The <code>-m</code> flag in the CLI tools pre-release returns a warning that <code>-M</code> should be used.</p> <p>Using <code>-M</code> and <code>-m</code> works, but seems redundant.  Using <code>-M</code> by itself runs the REPL.</p> <pre><code>clojure -M -m full.namespace.to.dash-main\n</code></pre> <p><code>-M</code> seems useful when including an alias with extra configuration (eg. <code>:extra-deps</code>, <code>:extra-paths</code>, <code>:main-opts</code>).  As <code>:main-opts</code> is no different to the <code>-m</code> option, creating an alias just to avoid the warning seems excessive.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-project-using-edn-style-args","title":"Task: Executing a project - using Edn style args","text":"<p>Clojure CLI tools is encouraging a move to functions that take a hash-map for their arguments.  Passing arguments in as an edn data structure has more rigor than options and strings on the command line.</p> <p>The simplest form is to define an alias to run the project, specifying just the function to execute using <code>:exec-fn</code></p> <pre><code> :aliases\n {:project/run\n   {:exec-fn practicalli.banking-on-clojure/server-start}\n } ;; End of Aliases\n</code></pre> <p>Then the project can be run using this alias.</p> <pre><code>clojure -X:project/run\n</code></pre> <p>Arguments can be passed to the function as key/value pairs on the command line.</p> <pre><code>clojure -X:project/run  :port 8080 :host \"localhost\"\n</code></pre> <p><code>:exec-args</code> provides a way to define default arguments for the function, regardless of if it is defined in <code>;:exec-fn</code> or passed via the command line.</p> <p><code>:exec-args</code> defines a hash-map of arguments so the function must support taking a hash-map as an argument.</p> <p>A function may take variable args, especially if it is supporting both hash-maps and strings as options.</p> <pre><code> :aliases\n {:project/run\n   {:exec-fn fully.qualified/namespace\n    :exec-args {:default \"arguments\" :can-be-over-ridden-by \"command-line-args\"} }\n } ;; End of Aliases\n</code></pre> <p>Adding <code>:exec-args</code> to the <code>:run-project</code></p> <pre><code> :aliases\n {:project/run\n   {:exec-fn practicalli.banking-on-clojure/server-start\n    :exec-args {:port 8888 :host \"localhost\"}}\n } ;; End of Aliases\n</code></pre>"},{"location":"reference/clojure-cli/example-alias-definitions/#example-of-running-a-clojure-project-hello-world","title":"Example of running a Clojure project - hello-world","text":"<p>In this example I use the hello-world example from https://clojure.org/guides/deps_and_cli#_writing_a_program A project <code>deps.edn</code> file was created containing the dependency for clojure.java-time and the source code from that page copied into <code>src/hello.clj</code></p> <p><code>clojure -m</code> hello runs the project and returns the time from running the -main function. However this gives a warning:</p> <pre><code>WARNING: When invoking clojure.main, use -M\n</code></pre> <p><code>clojure -M</code> runs a REPL</p> <p><code>clojure -M -m hello</code> runs the project and returns the time.  But then I ask myself what is the purpose of -M</p> <p>Creating an alias to run the project seems an interesting idea, as I could also set default arguments.</p> <p>Adding an <code>:project-run</code> alias to the project <code>deps.edn</code> works when calling with clojure <code>-M:project-run</code></p> <pre><code> :aliases\n {:project-run {:main-opts [\"-m\" \"hello\"]}}\n</code></pre> <p>Changing the <code>:project-run</code> alias to use <code>:exec-fn</code> and a fully qualified function (-main by default) should work when calling with <code>clojure -X:project-run</code>.  :aliases  {:run-project {:exec-fn hello]}}</p> <p>However, the <code>hello-world</code> project has an unqualified function and cannot be resolved.</p> <p>Moving the source code to <code>src/practicalli/hello.clj</code> and calling <code>clojure -X:run-project</code> gives an execution error, <code>(ArityException)</code> as the <code>-main</code> function does not take any arguments, <code>(defn -main [] ,,,)</code>.</p> <p>Changing the <code>-main</code> function to <code>(defn -main [&amp; args] ,,,)</code> fixes the arity exception and calling <code>clojure -X:run-project</code> works.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#local-maven-install","title":"Local Maven install","text":"<p>Install a jar into the local Maven cache, typically <code>~/.m2/repository/</code> directory, organised by groupId</p> <pre><code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'\n</code></pre> <p>edn strings must be in double quotes, and then single-quoted for the shell</p> <p><code>mvn-install</code> uses the <code>.pom</code> file contained in the jar (if it exists) to determine the groupId, artifactId, and version coordinates to use when the jar is installed.</p> <p>The <code>.pom</code> file can also be specified using the  <code>:pom</code> argument.</p> <p>The install argmap takes the following options:</p> key Required Description <code>:jar</code> required path to the jar file to install <code>:pom</code> optional path to .pom file (if .jar file does not contain .pom) <code>:lib</code> optional qualified symbol e.g <code>my.org/lib</code> <code>:version</code> optional Version number of library (string type) <code>:classifier</code> optional (string type) <code>:local-repo</code> optional path to local repo (default = ~/.m2/repository)"},{"location":"reference/clojure-cli/jvm-options/","title":"Reference: Clojure CLI JVM Options","text":"<p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p> <p>Java Virtual Machine options can be passed using the Clojure CLI, either via the <code>-J</code> command line flag or <code>:jvm-opts</code> in a <code>deps.edn</code> alias.</p> <p>Java Virtual Machine configuration and reporting</p> <p>Java Virtual Machine section covers commonly used options, reporting JVM metrics and optimisation of the JVM process.</p>"},{"location":"reference/clojure-cli/jvm-options/#clojure-cli-command-line-options","title":"Clojure CLI command line options","text":"<p>Clojure CLI <code>-J</code> flag passes configuration options to the JVM. When there are multiple, each must be prefixed with <code>-J</code>.</p> <pre><code>clojure -J-XX:+UnlockDiagnosticVMOptions -J\u2011XX:NativeMemoryTracking=summary -J\u2011XX:+PrintNMTStatistics\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#clojure-cli-depsedn-configuration","title":"Clojure CLI deps.edn configuration","text":"<p><code>:jvm-opts</code> key in an alias adds JVM options to Clojure CLI deps.edn configuration.  The <code>:jvm-opts</code> key has a value that is a collection of string JVM options <code>[\"-Xms2048m\" \"-Xmx4096\"]</code></p> <p>Alias to set a large heap size</p> <pre><code>:jvm/heap-max-2g {:jvm-opts [\"-Xmx2G\"]}\n</code></pre> <p>Report a full breakdown of the HotSpot JVM\u2019s memory usage upon exit using the following option combination:</p> <pre><code>:jvm/report {:jvm-opts [\"-XX:+UnlockDiagnosticVMOptions\"\n                        \"\u2011XX:NativeMemoryTracking=summary\"\n                        \"\u2011XX:+PrintNMTStatistics\"]}\n</code></pre> <p>Add a Java module</p> <pre><code>:jvm/xml-bind {:jvm-opts [\"\u2013add-modules java.xml.bind\"]}\n</code></pre> <p>Ignoring unrecognised options</p> <pre><code>:jvm-opts [\"-XX:+IgnoreUnrecognizedVMOptions\"]\n</code></pre> <p>The aliases can be used with the Clojure CLI execution options: <code>-A</code> (for built-in REPL invocation), <code>-X</code> and <code>-T</code> (for clojure.exec function execution), or <code>-M</code> (for clojure.main execution).</p> <p><code>-J</code> JVM options specified on the command line are concatenated after the alias options</p>"},{"location":"reference/clojure-cli/jvm-options/#calling-a-clojure-uberjar","title":"Calling A Clojure Uberjar","text":"<p>JVM options must be specified when calling an uberjar with the <code>java</code> command, <code>:jvm-opts</code> in the project <code>deps.edn</code> are not used with the <code>java</code> command</p> <pre><code>java -jar project-uberjar.jar -J...\n</code></pre> <p>Use <code>JDK_JAVA_OPTIONS</code> to define JVM options</p> <p><code>JDK_JAVA_OPTIONS</code> environment variable is used to define options that are used whenever the <code>java</code> command is called, greatly simplifying <code>java</code> commands.</p> <p>The <code>JDK_JAVA_OPTIONS</code> environment variable can be used with deployment systems and passed to container environments to simplify adjustment of resources used by the JVM process.</p>"},{"location":"reference/clojure-cli/jvm-options/#clojure-related-jvm-options","title":"Clojure related JVM options","text":"<p>Specify options or system properties to set up the Clojure service</p> <p><code>-Dclojure.compiler.disable-locals-clearing=true</code> - make more info available to debuggers</p> <p><code>-Dclojure.main.report=stderr</code> - print stack traces to standard error instead of saving to file, useful if process failing on startup</p> <p><code>-Dclojure.spec.skip-macros=false</code> - skip spec checks against macro forms</p>"},{"location":"reference/clojure-cli/jvm-options/#memory-management","title":"Memory Management","text":"<p><code>-XX:CompressedClassSpaceSize=3G</code> - prevent a specific type of OOMs</p> <p><code>-XX:MaxJavaStackTraceDepth=1000000</code> - prevents trivial Stack Overflow errors</p> <p><code>-Xmx24G</code> - set high maximum heap, preventing certain types of Out Of Memory errors (ideally high memory usage should be profiled if cause not known)</p> <p><code>-Xss6144k</code> - increase stack size x6 to prevent Stack Overflow errors</p> <p>The current default can be found with <code>java -XX:+PrintFlagsFinal -version 2&gt;/dev/null | grep \"intx ThreadStackSize\"</code></p> <p><code>-Xms6G</code> - Set minimum memory that is equal or greater than memory used by a running REPL, to improve performance</p> <p><code>-Xmx1G</code> - limit maximum heap allocation so a process can never use more memory, useful for environments with limited memory resources</p> <pre><code>:jvm/mem-max1g {:jvm-opts [\"-Xmx1G\"]}\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#container-memory-management","title":"Container Memory Management","text":"<p><code>JDK_JAVA_OPTIONS</code> environment variable should be used for setting JVM options within a container or in the provisioning service (e.g. Kubernettes / Argo CD) that deploys containers.</p> <p>Use JVM options that optimise running in a container</p> <ul> <li> <p><code>-XshowSettings:system</code> to output the resources the JVM believes it has access too, a very simple diagnostic tool to include</p> </li> <li> <p><code>-XX:+UseContainerSupport</code> instruct the JVM that it is running in a container environment, disabling the checks the JVM would otherwise carry out to determine if it was running in a container.  Can save a very small amount of start up time, though mainly used to ensure the JVM knows its in a container.</p> </li> <li> <p><code>-XX:MaxRAMPercentage=90</code> to set a relative maximum percentage of heap to use, based on the memory available from the host, e.g. <code>-XX:MaxRAMPercentage=80</code> will use a heap size of 80% of the available host memory</p> </li> </ul>"},{"location":"reference/clojure-cli/jvm-options/#dockerfile-example-with-jdk_java_options-environment-variable","title":"Dockerfile example with JDK_JAVA_OPTIONS environment variable","text":"<p>In this <code>Dockerfile</code> excerpt the <code>JDK_JAVA_OPTIONS</code> environment variable is used to print out the resources the JVM believes it has access to at startup. The JVM is instructed that it is running in a container environment and should use a maximum 90% heap size of the hosts memory resource.</p> <pre><code>ENV JDK_JAVA_OPTIONS \"-XshowSettings:system -XX:+UseContainerSupport -XX:MaxRAMPercentage=90\"\nCMD [\"java\", \"-jar\", \"/opt/practicalli-service.jar\"]\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#low-latency-systems","title":"Low latency systems","text":"<p>For systems that require very low latency, use the Z Garbage collector</p> <pre><code>\"-XX:+UnlockExperimentalVMOptions -XX:+UseZGC\"\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#stack-traces","title":"Stack traces","text":"<p><code>-XX:+TieredCompilation</code> - enable tiered compilation to support accurate bench-marking (increases startup time)</p> <p><code>-XX:-OmitStackTraceInFastThrow</code> - don't elide stack traces</p>"},{"location":"reference/clojure-cli/jvm-options/#startup-options","title":"Startup options","text":"<p><code>-Xverify:none</code> option reduces startup time of the JVM by skipping verification process</p> <pre><code>\"-Xverify:none\"\n</code></pre> <p>The verification process is a valuable check, especially for code that has not been run before.  So the code should be run through the verification process before deploying to production.</p>"},{"location":"reference/clojure-cli/jvm-options/#benchmark-options","title":"Benchmark options","text":"<p>Enable various optimizations, for guaranteeing accurate benchmarking (at the cost of slower startup):</p> <p><code>\"-server\"</code></p>"},{"location":"reference/clojure-cli/jvm-options/#graphical-ui-related-options","title":"Graphical UI related options","text":"<p><code>-Djava.awt.headless=true</code> - disable all UI features for disabling the clipboard for personal security:</p> <p><code>-Dapple.awt.UIElement=true</code> - remove icon from the MacOSX Dock</p> <p><code>-Dclash.dev.expound=true</code> - ?</p>"},{"location":"reference/clojure-cli/jvm-options/#garbage-collection","title":"Garbage Collection","text":"<p>Setup GC with short STW pauses which can be relevant for very high web server workloads</p> <pre><code>:jvm/g1gc\n{:jvm-opts [\"-XX:+UseG1GC\"\n            \"-XX:MaxGCPauseMillis=200\"\n            \"-XX:ParallelGCThreads=20\"\n            \"-XX:ConcGCThreads=5\"\n            \"-XX:InitiatingHeapOccupancyPercent=70\"]}\n</code></pre> <ul> <li>Source: Tuning Garbage Collection with Oracle JDK</li> </ul>"},{"location":"reference/clojure-cli/jvm-options/#view-jvm-options-of-a-running-jvm-process","title":"View JVM options of a running JVM process","text":"<p>Use a JMX client, e.g. VisualVM</p> <p><code>jcmd pid VM.system_properties</code> or <code>jcmd pid VM.flags</code> using <code>jcmd -l</code> to get the pid of the JVM process</p> <p>On Linux <code>ps -ef | grep java</code> which includes the options to run the JVM process, <code>ps -auxww</code> to show long arguments</p> <p>Getting the parameters of a running JVM</p>"},{"location":"reference/clojure-cli/jvm-options/#references","title":"References","text":"<p>JVM Options cheatsheet - JRebel</p>"},{"location":"reference/clojure-svg/","title":"Clojure Scalable Vector Graphics - SVG","text":"<p>Scalable Vector Graphics, SVG, is an image format for two-dimensional (2D) graphics.</p> <p>An SVG image uses data to describe how to draw an image, ensuring that images can shrink and scale easily and retain a high quality image.  As images are formed from data, shapes can easily be combined or intersected to form new shapes.  Using a data format also means SVG images can be created from code and therefore animated.</p> <p>Raster image formats like gif, jpeg and png use a grid of squares called pixels to define an image (also known as a bitmap). Each pixel has a colour and position in an image.  When zooming into an image the pixels grow larger distorting the sharpness of an image, referred to as pixelation, .Multiple versions of raster images are often created at different resolutions to reduce the loss of quality when viewed at different sizes.</p>"},{"location":"reference/clojure-svg/#hintwork-in-progress","title":"Hint::Work in progress","text":""},{"location":"reference/clojure-svg/#concepts","title":"Concepts","text":"<ul> <li>viewbox</li> <li>style - border, background, width, height, stoke, fill, draw (path)</li> <li>shapes - circle, path</li> </ul>"},{"location":"reference/clojure-svg/#viewbox","title":"Viewbox","text":"<p>A viewbox defines a co-ordinate system for the image. Defining a size for the viewbox defining a frame for the image where positions are relative to that frame, irrespective of the size of the image or how that image is scaled.</p> <p>A viewbox size should be selected to make the image as simple as possible to define within itself.</p> <p>Example: tictactoe O's and X's and the grid that represents the board.</p> <p>tictactoe O's and X's and the grid that represents the board</p>"},{"location":"reference/clojure-svg/#related-projects","title":"Related projects","text":"<ul> <li>TicTacToe with ClojureScript, Reagent and SVG</li> <li>System monitoring</li> <li>Practicalli SVG examples library</li> <li>Programming SVG with Clojure (TODO)</li> </ul>"},{"location":"reference/clojure-svg/#references","title":"References","text":"<ul> <li>SVG: Scalable Vector Graphics - Mozilla Developer network</li> </ul>"},{"location":"reference/clojure-syntax/assigning-names/","title":"Assigning Names","text":"<p>If we have to type the same values over and over, it would be very hard to write a program. What we need are names for values, so we can refer to them in a way we can remember. We do that using <code>def</code>.</p> <pre><code>(def mangoes 3)\n(def oranges 5)\n(+ mangoes oranges)\n</code></pre> <p>When you assign a name to a value, that name is called a symbol. You can assign more than simple values to symbols. Try the following:</p> <pre><code>(def fruit (+ mangoes oranges))\n(def average-fruit-amount (/ fruit 2))\naverage-fruit-amount\n</code></pre> <p>Look at the last line, and see how we can use symbols by themselves to refer to a value.</p> <p>Note Take the Clojure syntax you have learnt to far and write a metric/imperial converter</p> <p>Take your height in feet and inches and convert it to inches using arithmetic in Clojure.</p> <p>Then convert that to centimeters. There are 2.54 centimeters in an inch.</p> <p>Lastly, ask two people near you for their height in centimeters. Find the average of your heights.</p> <p>Note Bonus: Convert that average back to feet and inches. The feet and the inches will be separate numbers. <code>(quot x y)</code> will give you the whole number part when dividing two numbers. <code>(mod x y)</code> will give you the remainder when dividing two numbers.</p>"},{"location":"reference/clojure-syntax/code-documentation/","title":"Code documentation","text":"<p>Clojure functions are documented by adding a string to the function definition, after the function name.  This is referred to as the doc string.</p> <pre><code>(defn example-function\n  \"This is the documentation for this function, referred to as a doc string\"\n  [arguments]\n  (str \"some behaviour\"))\n</code></pre> <p><code>def</code> bindings can also be documented to provide context to the data the name is bound to.</p> <pre><code>(def weather-data\n  \"Data set for weather across the major capitals of Europe\"\n  [{:date \"2020-05-015\" :city \"Berlin\" :temperature-max 24 :temperature-min 13 :rainfall 1}\n   {:date \"2020-05-015\" :city \"Amsterdam\" :temperature-max 25 :temperature-min 14 :rainfall 0}])\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#write-easily-understandable-docstrings","title":"Write easily understandable docstrings","text":"<p>Practically recommends including specific details of the arguments passed to a function and the expected return type.  Including this at the end of the docstring makes that information very quick to find.</p> <pre><code>  \"Geographic visualization data set generator\n\n  Arguments:\n  - combined data set of GeoJSON and Cases\n  - maximum integer value for scale\n  Returns:\n  - Oz view hash-map\"\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#reading-source-code","title":"Reading source code","text":"<p><code>clojure.repl/source</code> will show the source code of a given function, which can be a valuable way to understand the function.  Reading function source code also provides ideas when writing custom Clojure code.</p> <p>Reading the source code for <code>clojure.core</code> functions is a good way to learn those functions, although some functions have been optimised for performance and are harder to follow.</p> <p>Source code for clojure.core is available online and is also linked to from the function descriptions on clojuredocs.org.</p>"},{"location":"reference/clojure-syntax/code-documentation/#writing-your-own-documentation","title":"Writing your own documentation","text":"<p>Writing good documentation for your own functions take practice which pays off in the long run.</p> <pre><code>()\n</code></pre> <pre><code>(defn my-function\n  \"I should practice writing clear and meaningful documentation for my functions.\n  Arguments: brief description of arguments\"\n  [arguments]\n  (str \"I should write pure functions where ever possible. \"\n       \"Each function should have a specific purpose. \"\n       \"A function should be clean and easy to read.\"))\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#notedefine-your-own-function","title":"Note::Define your own function","text":"<p>Practice writing a meaningful documentation in the doc string</p>"},{"location":"reference/clojure-syntax/comments/","title":"Comments","text":"<p>As well as the classic line comments, Clojure also can comment specific parts of the code structure, even when it run over multiple lines.</p> <p><code>;;</code> to comment a whole line and <code>;</code> to add a comment after the start of a line</p> <p><code>(comment )</code> wraps forms and returns <code>nil</code> when evaluated, referred to as rich comments</p> <p><code>#_</code> to ignore the next form as if it has not been written, commonly used for debugging</p>"},{"location":"reference/clojure-syntax/comments/#line-comments","title":"Line comments","text":"<p>Add general documentation for a namespace, such as a comment header that describes the overall purpose of a namespace.</p> <p>Separate a namespace into logical sections to aid navigation and help identify opportunities to refactor a namespace as it grows.</p>"},{"location":"reference/clojure-syntax/comments/#comment-function","title":"comment function","text":"<p>The <code>(comment ,,,)</code> function is used to included code that is only run by the developer directly.</p> <pre><code>(comment (map + [1 2 3] [1 2 3]))\n</code></pre> <p>The <code>comment</code> function returns <code>nil</code> so its advised not to use it inside another form.  For example:</p> <pre><code>(map + [1 2 3] (comment [1 2 3])) ; nil will be passed to map as the third argument\n</code></pre> <p>This will fail as it tries to use the <code>+</code> function to add <code>1</code> to <code>nil</code></p> <p>The <code>#_</code> is the appropriate comment style for this example</p>"},{"location":"reference/clojure-syntax/comments/#rich-comment","title":"Rich comment","text":"<p>The <code>comment</code> expression is referred to a a rich comment, as it is often used to evaluate expressions it contains as part of a REPL driven development workflow.</p> <p>Unlike line comments, forms inside a comment block can be evaluated in a Clojure aware editor to help the developer work with a project.</p> <p>Rich comment are useful for rapidly iterating over different design decisions by including the same function but with different implementations. Hide clj-kondo linter](/clojure-cli/install/install-clojure.html#clj-kondo-static-analyser--linter) warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n\n  ) ;; End of rich comment block\n</code></pre> <p>The expressions can represent example function for using the project, such as starting/restarting the system, updating the database, etc.</p> <p></p> <p>Expressions in rich comment blocks can also represent how to use a namespace API, providing examples of arguments to supply to further convey meaning to the code.</p> <p>These rich comments make a project more accessible and easier to use.</p> <p>The \"Rich\" in the name also refers to Rich Hickey, the author and benevolent leader of the Clojure language.</p>"},{"location":"reference/clojure-syntax/comments/#comment-forms-with-the-comment-reader-macro","title":"Comment forms with the comment reader macro","text":"<p><code>#_</code> is the comment reader macro that instructs the Clojure reader to completely ignore the next form, as if it had never been written.</p> <p>No value is returned, so this comment is safe to use within an expression.</p> <p>You can place <code>#_</code> before the start of a form and everything inside that form will be commented</p> <pre><code>#_(def my-data [1 2 3 4 5])\n</code></pre> <p><code>#_</code> will comment forms that span multiple lines, for example function definitions</p> <pre><code>#_(defn my-function\n        [args]\n        (str \"I am an experiment, so not always needed\"))\n</code></pre> <p><code>#_</code> can also be put on the line(s) before the Clojure form, which can make your code more readable and keep alignment of your code consistent.</p>"},{"location":"reference/clojure-syntax/comments/#debugging-with-comment-macro","title":"debugging with comment macro","text":"<p>As the comment macro can be used without returning a value, it can safely be added to code to help with debugging.</p> <p>This code example finds the most common word in the text of a book.  Most of the lines of code in the threading macro have been commented to discover what the non-commented code does.</p> <p>As each expression in the threading macros is understood, by looking at its results, comments can be removed to understand more of the code.</p> <pre><code>(defn most-common-words [book]\n  (-&gt;&gt; book\n       (re-seq #\"[a-zA-Z0-9|']+\" ,,,)\n       #_(map #(clojure.string/lower-case %))\n       #_(remove common-english-words)\n       #_frequencies\n       #_(sort-by val)\n       #_reverse\n       ))\n</code></pre> <p>This is an effective way to deconstruct parts of a larger Clojure expression.</p> <p>Watch episode #13 of Practicalli Clojure study group to see this in practice.</p>"},{"location":"reference/clojure-syntax/comments/#comment-nested-forms","title":"comment nested forms","text":"<p><code>#_</code> tells the reader to ignore the next form, it is therefore never evaluated and neither is the <code>#_</code>.  This means that <code>#_</code> can be used inside a nested form to comment just a part of the expression</p> <p>In this example the third vector of values is not read by the Clojure reader and therefore is not passed as an argument to <code>+</code> function by <code>map</code></p> <p><code>(map + [1 2 3] [4 5 6] #_[7 8 9])</code></p>"},{"location":"reference/clojure-syntax/comments/#stacking-comments","title":"Stacking comments","text":"<p>The comment reader macro has the ability to stack these comments on forms, so using <code>#_#_</code> will comment out two successive forms.</p> <p>In a <code>let</code> form we can comment out a name binding that is causing problems.  As the name and value are both forms, then we use a stacked <code>#_</code> to comment both out. We also do the same in the body of the let, so as to not include the evaluation of the string or <code>name2</code> local name in the <code>str</code> form.</p> <pre><code>(let [name1 \"value\"\n       #_#_name2 \"another-value]\n   (str \"First name is: \" name1 #_#_\" second name is: \" name2\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/","title":"Control Flow","text":"<p>The following section of functions gives examples of simple control flow.  As you gain more experience with Clojure, you will discover more functional ways to achieve the same (or better) results.</p> <p>Hint Although these functions may seem similar to other non-functional languages, there are subtle differences</p>"},{"location":"reference/clojure-syntax/control-flow/#if","title":"If","text":"<p>Using the <code>if</code> function you can test if an expression evaluates to true.  If it is true, the first value is returned, if its false the second value is returned.</p> <p>Here is a simple example to see if one number is bigger that another</p> <pre><code>(if (&gt; 3 2)\n  \"Higher\"\n  \"Lower\")\n\n=&gt; \"Higher\"\n</code></pre> <p>Here is an example of an condition inside an anonymous function.</p> <pre><code>(defn even-number [number]\n  (if (odd? number)\n    (inc number)\n    number))\n\n(even-number 41)\n;; =&gt; 42\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#when","title":"When","text":"<p>When a condition is true, then return the value of evaluating the next expression.  If the condition is false, then return <code>nil</code></p> <pre><code>    (when (&gt; 3 2)\n      \"Higher\")\n\n=&gt; \"Higher\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#case","title":"Case","text":"<p>When one of these things is true, do this, else default</p> <pre><code>(case (inc 3)\n  1 \"Not even close\"\n  2 \"I wish I was that young\"\n  3 \"That was my previous value\"\n  4 \"You sunk my battleship\"\n  \"I dont think you understood the question\")\n\n=&gt; \"You sunk my battleship\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#cond","title":"Cond","text":"<p>Return the associated value of the first condition that is true, or return the default value specified by <code>:otherwise</code></p> <pre><code>(cond\n  (= 7 (inc 2)) \"(inc 2) is not 7, so this condition is false\"\n  (= 16 (* 8 2)) \"This is the first correct condition so its associated expression is returned\"\n  (zero? (- (* 8 8) 64)) \"This is true but not returned as a previous condition is true\"\n  :otherwise \"None of the above are true\")\n\n;; =&gt; \"This is the first correct condition so its associated expression is returned\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#for","title":"For","text":"<p>Using the <code>for</code> function you can Iterate through the values in a collection and evaluate each value in tern with  with a condition, using either <code>:when</code> or <code>:while</code>.</p> <pre><code>(for [x (range 10) :when (odd? x)] x)\n\n(for [x (range 10) :while (even? x)] x)\n\n(for [x (range 10)\n      y (range 10)]\n  [x y])\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#while","title":"While","text":"<p>Do something while the condition is true</p> <pre><code>(while (condition)\n  (do something))\n</code></pre> <p>Here is a simple while example that uses a (mutable) counter and prints out the results to the repl window.</p> <pre><code>;; create a counter using a mutable counter\n(def counter (atom 10))\n\n;; While the counter is positive (is a number greater than zero), print out the current value of the counter.\n(while (pos? @counter)\n  (do\n    (println @counter)\n    (swap! counter dec)))\n</code></pre> <p>This example uses mutable state and causes a side effect by printing to the repl.  Both these kinds of things are typically kept to a minimum in Clojure.</p> <p>TODO An alternative would be to use use the iteration over a collection to control the while condition</p>"},{"location":"reference/clojure-syntax/defining-functions/","title":"Defining Functions","text":"<p><code>clojure.core/defn</code> defines a custom function that can be called from anywhere in the current namespace by just using the name.  A defined function can be called from where ever its namespace is required in other namespaces.</p> <p>Here is a simple function definition that takes a number and divides it by two</p> <pre><code>    (defn half-a-number\n      \"Divide a given number by 2\"\n      [number]\n      (/ number 2))\n</code></pre> <p>Once you have defined a function, you can call it by using the function name as the first element of a list, <code>()</code>.  Any other elements in the list are arguments passed to the function.</p> <pre><code>    (half-a-number 4)\n</code></pre>"},{"location":"reference/clojure-syntax/defining-functions/#understanding-the-defn-syntax","title":"Understanding the <code>defn</code> syntax","text":"<p>The standard form of <code>defn</code>:</p> <pre><code>(defn name doc-string? attr-map? [params*] prepost-map? body)\n</code></pre> <p>name is a symbol used to call the function.</p> <p>doc-string? is an optional string used to provide a meaningful description of the function definition.  This description is the living documentation of the function and can be accessed via `clojure.repl/doc** functions and Clojure aware editors.</p> <p>attr-map? is an optional map for pre-conditions for a function.</p> <p>[params*] is a zero or more vector of symbols that represent the arguments passed to a function.  The number of symbols defined must be matched when calling the function, or an exception will occur.</p> <p>prepost-map? an optional map for post-conditions for a function.</p> <p>body is the algorithm that will evaluate when the function is called.</p> <p>There is a second form of the <code>defn</code> function, one which responds differently based on the number of arguments used to call the function (polymorphic).</p> <pre><code>(defn name doc-string? attr-map?\n  ([params*] prepost-map? body) + attr-map?)\n</code></pre> <p>Thinking Functionally - Polymorphism has examples of using defn to define polymorphic functions</p>"},{"location":"reference/clojure-syntax/defining-functions/#breaking-down-the-defn-syntax","title":"Breaking down the defn syntax","text":"<p>The syntax <code>defn</code> is what we call a macro, it is a simpler way to write clojure code that does the same thing.</p> <p>You can think of defining a function with <code>defn</code> as two steps</p> <ol> <li>Give the function a name - using the <code>def</code> syntax</li> <li>Define the functions behaviour and arguments it takes - using the <code>fn</code> syntax</li> </ol> <p>Here is the same function if you typed it out in full</p> <pre><code>    (def half-a-number\n      (fn [number]\n        (/ number 2)))\n</code></pre>"},{"location":"reference/clojure-syntax/defining-functions/#hintmacroexpand-functions","title":"Hint::Macroexpand functions","text":"<p>The <code>macroexpand-1</code> function takes an expression that includes one or more macros and returns the expanded version of Clojure code. The <code>macroexpand-all</code> will also expand macros into Clojure code, doing so recursively for all macros it finds.</p> <p>Clojure editors also provide evaluation functions that will macroexpand.</p>"},{"location":"reference/clojure-syntax/global-definitions/","title":"Global definitions","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/java-interop/","title":"Java Interoperability","text":"<p>Clojure provides very clear and simple syntax for Java interoperability, using the following functions</p> <ul> <li><code>import</code> - add functions from the Java library into the current namespace</li> <li><code>new</code> - create a new Java object</li> <li><code>.</code> - is the short form of the <code>new</code> function</li> </ul> <p>As Clojure is hosted on the Java Virtual Machine (JVM), its very easy to include libraries from any other languages that runs on the JVM, for example Java, Groovy, Scala, Jython, JRuby, Jaskell, etc.</p> <p>The Leiningen build tool provides a simple way to include libraries as dependencies, using the <code>:dependencies</code> section of the <code>project.clj</code> file. Any library published to Maven Central is available for download by Leiningen, as both Maven Central and Clojars.org repositories are used by default.</p> <p>java.lang included</p> <p>Clojure projects and REPL environments include the <code>java.lang</code> library automatically.  Any methods from that library can be used without having to <code>import</code> them or include any dependencies</p>"},{"location":"reference/clojure-syntax/java-interop/#the-syntax","title":"The syntax","text":"<p>Its very easy to call Java methods and objects from clojure using the following syntax</p> <pre><code>(.instanceMember instance args*)\n(.instanceMember Classname args*)\n(.-instanceField instance)\n(Classname/staticMethod args*)\nClassname/staticField\n</code></pre> <p>Note Use the instanceMember .toUpperCase to convert a string from lower case to upper case</p> <p>Call the <code>.toUpperCase</code> function on any string you like, for example</p> <pre><code>(.toUpperCase \"I was low, but now I'm up\")\n</code></pre> <p>The string passed as an argument should now be all uppercase: \"I WAS LOW, BUT NOW I'M UP\"</p> <p>Note Use the staticField <code>Math/PI</code> to return the approximate value of Pi</p> <p>You can treat any static field like any name defined in your Clojure code, so when evaluated the static field simply returns the value it represents</p> <p>In this case the <code>Math/PI</code> static field simply returns the approximate value of Pi that fits into a java.lang.Double type.</p> <pre><code>Math/PI\n-&gt; 3.141592653589793\n</code></pre>"},{"location":"reference/clojure-syntax/java-interop/#getting-the-java-environment","title":"Getting the Java environment","text":"<p>Earlier we used Clojure functions to find information about our environment.  We can also used the <code>getProperty()</code> method from the <code>java.lang.System</code> object to ask for the java version and jvm name.</p> <p>Note Get version of Java &amp; the JVM, returning those values as a meaningful string.  Then get the version of the Clojure project</p> <pre><code>(str \"You are running Java version \" (System/getProperty \"java.version\") \"with the JVM\" (System/getProperty \"java.vm.name\"))\n\n(str \"Latest project version: \" (System/getProperty \"playground.version\"))\n</code></pre> <p>Note Use <code>System/getenv</code> to return your system's environment variables as a map</p> <pre><code>(System/getenv)\n</code></pre> <p></p> <p>You may notice that this is a map data structure that we return, so we can use use destructuring or the maps behaviour itself to pull out information.</p> <p>Hint A full list of properties can be seen in the getProperty() documentation</p> <p>There are more examples of Java Interoperability in the next few sections.</p>"},{"location":"reference/clojure-syntax/local-bindings/","title":"Local Bindings","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/more-java-fun/","title":"More Java fun","text":"<p>Lets try some more examples to show how easy it is to use Java methods and objects.  Remember that everything in java.lang is available in your Clojure project by default</p>"},{"location":"reference/clojure-syntax/more-java-fun/#returning-specific-types","title":"Returning specific types","text":"<p>Clojure has types, after all it runs on the JVM and included <code>java.lang</code> library in ever project.  Types are inferred at runtime, saving you the need to design types yourself.</p> <p>Sometimes you want to ensure a value is of a particular type and you can use Java to do this.</p> <p>Note Return a string value as an integer</p> <p>When you create a new <code>java.lang.Integer</code> object you can provide a default value by passing either a number or string type.</p> <pre><code>(new Integer \"123\")\n\n;; Or the more common short-hand forms\n\n(Integer. \"123\")\n</code></pre> <p>This is the equivalent to the Java code:</p> <pre><code> Integer myInt = new Integer(\"123\");\n</code></pre> <p>The <code>.</code> function essentially instantiates a new object from the class, in this case <code>Integer</code>, passing any arguments to its constructor.</p> <p>Hint Example: converting the port number read from an environment variable as a string which needs to be passed to the Jetty server as a number.  See the Clojure Webapp workshop an example.</p> <p>More on types in the section a quick look at types</p> <p>fixme The following is work in progress</p>"},{"location":"reference/clojure-syntax/more-java-fun/#using-java-date","title":"Using Java date","text":"<p>Note Use <code>java.util.Date</code> to explore date and time</p> <pre><code>(import java.util.Date)\n\n(Date.)\n\n(def now (Date.))\n\n(str now)\n</code></pre> <p></p> <p>Its easy to create a local reference to a Java Date object instance and then call methods on that date object</p> <pre><code>(let [date (java.util.Date.)] (.getHours date))\n</code></pre> <p>Or using the threading macro, we can make the code a little clearer</p> <pre><code>(-&gt;\n   (java.util.Date.)\n   (.getHours))\n</code></pre>"},{"location":"reference/clojure-syntax/more-java-fun/#its-joda-time","title":"Its Joda Time","text":"<p><code>clj-time</code> is a Clojure wrapper for Joda time.  As this is an external library, you need to add it to your project.clj file as a dependency.  To find the latest version, check the clj-time library on Clojars.org</p> <p>Note Add the clj-time dependency to your project (restart needed), require the clj-time library in your code and use the functions <code>now</code>, <code>formatters</code>&amp; <code>unparse</code></p> <pre><code>(require '[clj-time.core :as time])\n(require '[clj-time.format :as time-format])\n\n(time/now)\n\n;; ISO 8601 UTC format\n(def time-formatter (time-format/formatters :basic-date-time))\n(time-format/unparse custom-formatter (date-time 2010 10 3))\n</code></pre>"},{"location":"reference/clojure-syntax/more-java-fun/#swing-coding","title":"Swing coding","text":"<p>Swing GUI coding in Java feels quite messy to me, however using Swing in Clojure feels much cleaner.  Using the <code>doto</code> function allow you to chain function (Java method) calls together.</p> <p>Note  Start with the <code>import</code> function to add the necessary swing libraries.  Then create a button and add it to a panel, adding that panel to a frame.</p> <pre><code>(import '(javax.swing JFrame JPanel JButton))\n(def button (JButton. \"Click Me!\"))\n(def panel (doto (JPanel.)\n             (.add button)))\n(def frame (doto (JFrame. \"Hello Frame\")\n             (.setSize 200 200)\n             (.setContentPane panel)\n             (.setVisible true)))\n</code></pre> <p>Let\u2019s make our button show a message using an JOptionPane/showMessageDialog widget</p> <pre><code>(import 'javax.swing.JOptionPane)\n(defn say-hello []\n  (JOptionPane/showMessageDialog\n    nil \"Hello, World!\" \"Greeting\"\n    JOptionPane/INFORMATION_MESSAGE))\n</code></pre> <p>To connect this function to our button, write a class implementing the ActionListener interface.  Clojure\u2019s proxy feature is the easiest way to do this:</p> <pre><code>(import 'java.awt.event.ActionListener)\n(def act (proxy [ActionListener] []\n           (actionPerformed [event] (say-hello))))\n</code></pre> <p><code>act</code> is an instance of an anonymous class implementing the actionPerformed method, so attach this class as a listener the button</p> <pre><code>(.addActionListener button act)\n</code></pre> <p>Now evaluate the <code>say-hello</code> function to see the new button in action.</p> <pre><code>(say-hello)\n</code></pre> <p>Hint Seesaw is a really nice library for swing development.  Also talk a look at the Seesaw minesweeper series.</p>"},{"location":"reference/clojure-syntax/more-java-fun/#understanding-the-dot-special-form","title":"Understanding the dot special form","text":"<p>Fixme This section onwards needs reworking</p> <p>All of these examples (except java.lang.Math/PI) use macros which expand to use the dot special form. In general, you won't need to use the dot special form unless you want to write your own macros to interact with Java objects and classes. Nevertheless, here is each example followed by its macroexpansion:</p> <pre><code>(macroexpand-1 '(.toUpperCase \"By Bluebeard's bananas!\"))\n; =&gt; (. \"By Bluebeard's bananas!\" toUpperCase)\n\n(macroexpand-1 '(.indexOf \"Synergism of our bleeding edges\" \"y\"))\n; =&gt; (. \"Synergism of our bleeding edges\" indexOf \"y\")\n\n(macroexpand-1 '(Math/abs -3))\n; =&gt; (. Math abs -3)\n</code></pre> <p>You can think of the general form of the dot operator as:</p> <pre><code>(. object-expr-or-classname-symbol method-or-member-symbol optional-args*)\n</code></pre> <p>There are a few more details to the dot operator than that, and if you're interested in exploring it further you can look at clojure.org's documentation on Java interop.</p> <p>Input/output involves resources, be they files, sockets, buffers, or whatever. Java has separate classes for reading a resource's contents, writings its contents, and for interacting with the resource's properties.</p> <p>For example, the java.io.File class is used to interact with a file's properties. Among other things, you can use it to check whether a file exists, to get the file's read/write/execute permissions, and to get its filesystem path:</p> <pre><code>(let [file (java.io.File. \"/\")]\n  (println (.exists file))\n  (println (.canWrite file))\n  (println (.getPath file)))\n; =&gt; true\n; =&gt; false\n; =&gt; /\n</code></pre> <p>Noticeably missing from this list of capabilities are reading and writing. To read a file, you could use the java.io.BufferedReader class or perhaps java.io.FileReader. Likewise, you can use the java.io.BufferedWriter or java.io.FileWriter class for writing. There are other classes available for reading and writing as well, and which one you choose depends on your specific needs. Reader and Writer classes all have the same base set of methods for their interfaces; readers implement read, close, and more, while writers implement append, write, close, and flush. So, Java gives you a variety of tools for performing IO. A cynical person might say that Java gives you enough rope to hang yourself, and if you find such a person I hope you give them just enough arms to hug them.</p> <p>Either way, Clojure makes things easier for you. First, there's spit and slurp. Spit writes to a resource, and slurp reads from one. Here's an example of using them to write and read a file:</p> <pre><code>(spit \"/tmp/hercules-todo-list\"\n\"- wash hair\n - charm the multi-headed snake\")\n\n(slurp \"/tmp/hercules-todo-list\")\n\n; =&gt; \"- wash hair\n; =&gt;  - charm the multi-headed snake\"\n</code></pre> <p>You can also use these functions with objects representing resources other than files. The next example uses a StringWriter, which allows you to perform IO operations on a string:</p> <pre><code>(let [s (java.io.StringWriter.)]\n  (spit s \"- charm the multi-headed snake\")\n  (.toString s))\n; =&gt; \"- charm the multi-headed snake\"\n</code></pre> <p>Naturally, you can also read from a StringReader with slurp:</p> <pre><code>(let [s (java.io.StringReader. \"- charm the multi-headed snake\")]\n  (slurp s))\n; =&gt; \"- charm the multi-headed snake\"\n</code></pre> <p>Of course, you can also use the read and write methods for resources. It doesn't really make much of a difference which you use; spit and slurp are often convenient because they work with just a string representing a filesystem path or a URL.</p> <p>The with-open macro is another convenience: it implicitly closes a resource at the end of its body. There's also the reader function, a nice utility which, according to the clojure.java.io api docs, \"attempts to coerce its argument to an open java.io.Reader.\" This is convenient when you don't want to use slurp because you don't want to try to read a resource in its entirety, and you don't want to figure out which Java class you need to use. You could use it along with with-open and the line-seq function if you're trying to read a file one line at a time:</p> <pre><code>(with-open [todo-list-rdr (clojure.java.io/reader \"/tmp/hercules-todo-list\")]\n  (doseq [todo (line-seq todo-list-rdr)]\n    (println todo)))\n; =&gt; \"- wash hair\n; =&gt;  - charm the multi-headed snake\"\n</code></pre> <p>That should be enough for you to get started with IO in Clojure. If you're trying to do something more sophisticated, definitely take a look at the clojure.java.io docs, the java.nio.file package docs, or the java.io package docs. 5. Summary</p> <p>In this chapter, you learned what it means for Clojure to be hosted on the JVM. Clojure programs get compiled to Java bytecode and executed within a JVM process. Clojure programs also have access to Java libraries, and you can easily interact with them using Clojure's interop facilities. 6. Resources</p>"},{"location":"reference/clojure-syntax/more-java-fun/#from-httpclojureorgjava_interop","title":"From http://clojure.org/java_interop","text":"<pre><code>(.instanceMember instance args*)\n(.instanceMember Classname args*)\n(.-instanceField instance)\n\n(.toUpperCase \"fred\")\n-&gt; \"FRED\"\n(.getName String)\n-&gt; \"java.lang.String\"\n(.-x (java.awt.Point. 1 2))\n-&gt; 1\n(System/getProperty \"java.vm.version\")\n-&gt; \"1.6.0_07-b06-57\"\nMath/PI\n-&gt; 3.141592653589793\n</code></pre> <p>The preferred idiomatic forms for accessing field or method members are given above. The instance member form works for both fields and methods. The instanceField form is preferred for fields and required if both a field and a 0-argument method of the same name exist. They all expand into calls to the dot operator (described below) at macroexpansion time. The expansions are as follows:</p> <pre><code>(.instanceMember instance args*) ==&gt; (. instance instanceMember args*)\n(.instanceMember Classname args*) ==&gt;\n    (. (identity Classname) instanceMember args*)\n(.-instanceField instance) ==&gt; (. instance -instanceField)\n(Classname/staticMethod args*) ==&gt; (. Classname staticMethod args*)\nClassname/staticField ==&gt; (. Classname staticField)\n</code></pre> <p>The Dot special form</p> <pre><code>(. instance-expr member-symbol)\n(. Classname-symbol member-symbol)\n(. instance-expr -field-symbol)\n(. instance-expr (method-symbol args*)) or\n(. instance-expr method-symbol args*)\n(. Classname-symbol (method-symbol args*)) or\n(. Classname-symbol method-symbol args*)\n</code></pre> <p>Special form.</p> <p>The '.' special form is the basis for access to Java. It can be considered a member-access operator, and/or read as 'in the scope of'.</p> <p>If the first operand is a symbol that resolves to a class name, the access is considered to be to a static member of the named class. Note that nested classes are named EnclosingClass$NestedClass, per the JVM spec. Otherwise it is presumed to be an instance member and the first argument is evaluated to produce the target object.</p> <p>If the second operand is a symbol and no args are supplied it is taken to be a field access - the name of the field is the name of the symbol, and the value of the expression is the value of the field, unless there is a no argument public method of the same name, in which case it resolves to a call to the method. If the second operand is a symbol starting with -, the member-symbol will resolve only as field access (never as a 0-arity method) and should be preferred when that is the intent.</p> <p>If the second operand is a list, or args are supplied, it is taken to be a method call. The first element of the list must be a simple symbol, and the name of the method is the name of the symbol. The args, if any, are evaluated from left to right, and passed to the matching method, which is called, and its value returned. If the method has a void return type, the value of the expression will be nil. Note that placing the method name in a list with any args is optional in the canonic form, but can be useful to gather args in macros built upon the form.</p> <p>Note that boolean return values will be turned into Booleans, chars will become Characters, and numeric primitives will become Numbers unless they are immediately consumed by a method taking a primitive.</p> <p>The member access forms given at the top of this section are preferred for use in all cases other than in macros.</p> <pre><code>(.. instance-expr member+)\n(.. Classname-symbol member+)\nmember =&gt; fieldName-symbol or (instanceMethodName-symbol args*)\n</code></pre> <p>Macro. Expands into a member access (.) of the first member on the first argument, followed by the next member on the result, etc. For instance:</p> <pre><code>(.. System (getProperties) (get \"os.name\"))\n</code></pre> <p>expands to:</p> <pre><code>(. (. System (getProperties)) (get \"os.name\"))\n</code></pre> <p>but is easier to write, read, and understand. See also the -&gt; macro which can be used similarly:</p> <pre><code>(-&gt; (System/getProperties) (.get \"os.name\"))\n</code></pre> <p>(doto instance-expr (instanceMethodName-symbol args)) Macro. Evaluates instance-expr then calls all of the methods/functions with the supplied arguments in succession on the resulting object, returning it.</p> <pre><code>(doto (new java.util.HashMap) (.put \"a\" 1) (.put \"b\" 2))\n-&gt; {a=1, b=2}\n</code></pre> <p>Note the above applies to the latest Clojure SVN revision. If you are using the 20080916 release only method calls are allowed, and the syntax is:</p> <pre><code>(doto (new java.util.HashMap) (put \"a\" 1) (put \"b\" 2))\n-&gt; {a=1, b=2}\n</code></pre> <p>(Classname. args) (new Classname args)</p> <p>Special form. The args, if any, are evaluated from left to right, and passed to the constructor of the class named by Classname. The constructed object is returned.</p> <p>Alternative Macro Syntax</p> <p>As shown, in addition to the canonic special form new, Clojure supports special macroexpansion of symbols containing '.':</p> <pre><code>(new Classname args*)\n</code></pre> <p>can be written</p> <pre><code>(Classname. args*)\n;; note trailing dot\n</code></pre> <p>the latter expanding into the former at macro expansion time.</p> <p>(instance? Class expr) Evaluates expr and tests if it is an instance of the class. Returns true or false</p> <p>(set! (. instance-expr instanceFieldName-symbol) expr) (set! (. Classname-symbol staticFieldName-symbol) expr) Assignment special form. When the first operand is a field member access form, the assignment is to the corresponding field. If it is an instance field, the instance expr will be evaluated, then the expr.</p> <p>In all cases the value of expr is returned.</p> <p>Note - you cannot assign to function params or local bindings. Only Java fields, Vars, Refs and Agents are mutable in Clojure.</p> <p>(memfn method-name arg-names*) Macro. Expands into code that creates a fn that expects to be passed an object and any args and calls the named instance method on the object passing the args. Use when you want to treat a Java method as a first-class fn.</p> <p>(map (memfn charAt i) [\"fred\" \"ethel\" \"lucy\"] [1 2 3]) -&gt; (\\r \\h \\y)</p> <p>Note it almost always preferable to do this directly now, with syntax like:</p> <p>(map #(.charAt %1 %2) [\"fred\" \"ethel\" \"lucy\"] [1 2 3]) -&gt; (\\r \\h \\y)</p> <p>(bean obj) Takes a Java object and returns a read-only implementation of the map abstraction based upon its JavaBean properties.</p> <p>(bean [[http://java.awt.Color/black|java.awt.Color/black]]) -&gt; {:RGB -16777216, :alpha 255, :transparency 1,     :class class java.awt.Color, :green 0, :blue 0,     :colorSpace java.awt.color.ICC_ColorSpace@c94b51, :red 0}</p> <p>Support for Java in Clojure Library Functions</p> <p>Many of the Clojure library functions have defined semantics for objects of Java types. contains? and get work on Java Maps, arrays, Strings, the latter two with integer keys. count works on Java Strings, Collections and arrays. nth works on Java Strings, Lists and arrays. seq works on Java reference arrays, Iterables and Strings. Since much of the rest of the library is built upon these functions, there is great support for using Java objects in Clojure algorithms.</p> <p>Implementing Interfaces and Extending Classes</p> <p>Clojure supports the dynamic creation of objects that implement one or more interfaces and/or extend a class with the proxy macro. The resulting objects are of an anonymous class. You can also generate statically-named classes and .class files with gen-class. As of Clojure 1.2, reify is also available for implementing interfaces.</p> <p>( proxy [class-and-interfaces] [args] fs+) class-and-interfaces - a vector of class names args - a (possibly empty) vector of arguments to the superclass constructor. f =&gt; (name [params] body) or (name ([params] body) ([params+] body) ...)</p> <p>Macro</p> <p>Expands to code which creates a instance of a proxy class that implements the named class/interface(s) by calling the supplied fns.</p> <p>A single class, if provided, must be first. If not provided it defaults to Object.</p> <p>The interfaces names must be valid interface types. If a method fn is not provided for a class method, the superclass method will be called.</p> <p>If a method fn is not provided for an interface method, an UnsupportedOperationException will be thrown should it be called.</p> <p>Method fns are closures and can capture the environment in which proxy is called. Each method fn takes an additional implicit first argument, which is bound to this.</p> <p>Note that while method fns can be provided to override protected methods, they have no other access to protected members, nor to super, as these capabilities cannot be a proxy.</p> <p>Arrays</p> <p>Clojure supports the creation, reading and modification of Java arrays. It is recommended that you limit use of arrays to interop with Java libraries that require them as arguments or use them as return values.</p> <p>Note that many other Clojure functions work with arrays such as via the seq library. The functions listed here exist for initial creation of arrays, or to support mutation or higher performance operations on arrays.</p> <p>Create array from existing collection: aclone amap to-array to-array-2d into-array Multi-dimensional array support: aget aset to-array-2d make-array Type-specific array constructors: boolean-array byte-array char-array double-array float-array int-array long-array object-array short-array Primitive array casts: booleans bytes chars doubles floats ints longs shorts Mutate an array: aset Process an existing array: aget alength amap areduce</p> <p>Type Hints</p> <p>Clojure supports the use of type hints to assist the compiler in avoiding reflection in performance-critical areas of code. Normally, one should avoid the use of type hints until there is a known performance bottleneck. Type hints are metadata tags placed on symbols or expressions that are consumed by the compiler. They can be placed on function parameters, let-bound names, var names (when defined), and expressions:</p> <p>(defn len [x]   (.length x))</p> <p>(defn len2 [^String x]   (.length x))</p> <p>user=&gt; (time (reduce + (map len (repeat 1000000 \"asdf\")))) \"Elapsed time: 3007.198 msecs\" 4000000 user=&gt; (time (reduce + (map len2 (repeat 1000000 \"asdf\")))) \"Elapsed time: 308.045 msecs\" 4000000</p> <p>Once a type hint has been placed on an identifier or expression, the compiler will try to resolve any calls to methods thereupon at compile time. In addition, the compiler will track the use of any return values and infer types for their use and so on, so very few hints are needed to get a fully compile-time resolved series of calls. Note that type hints are not needed for static members (or their return values!) as the compiler always has the type for statics.</p> <p>There is a warn-on-reflection flag (defaults to false) which will cause the compiler to warn you when it can't resolve to a direct call:</p> <p>(set! warn-on-reflection true) -&gt; true</p> <p>(defn foo [s] (.charAt s 1)) -&gt; Reflection warning, line: 2 - call to charAt can't be resolved. -&gt; #user/foo</p> <p>(defn foo [^String s] (.charAt s 1)) -&gt; #user/foo</p> <p>For function return values, the type hint can be placed before the arguments vector:</p> <p>(defn hinted   (^String [])   (^Integer [a])   (^java.util.List [a &amp; args]))</p> <p>-&gt; #user/hinted</p> <p>Aliases</p> <p>Clojure provides aliases for primitive Java types and arrays which do not have typical representations as Java class names. For example, long arrays (long-array []) have a type of \"[J\".</p> <pre><code>int - A primitive int\nints - An int array\nlong - A primitive long\nlongs - A long array\nfloat - A primitive float\nfloats - A float array\ndouble - A primitive double\ndoubles - A double array\nvoid - A void return\nshort - A primitive short\nshorts - A short array\nboolean - A primitive boolean\nbooleans - A boolean array\nbyte - A primitive byte\nbytes - A byte array\nchar - A primitive character\nchars - A character array\n</code></pre> <p>Support for Java Primitives</p> <p>Clojure has support for high-performance manipulation of, and arithmetic involving, Java primitive types in local contexts. All Java primitive types are supported: int, float, long, double, boolean, char, short, and byte.</p> <pre><code>let/loop-bound locals can be of primitive types, having the inferred, possibly primitive type of their init-form.\nrecur forms that rebind primitive locals do so without boxing, and do type-checking for same primitive type.\nArithmetic (+,-,*,/,inc,dec,&lt;,&lt;=,&gt;,&gt;= etc) is overloaded for primitive types where semantics are same.\naget/aset are overloaded for arrays of primitives\naclone, alength functions for arrays of primitives\nconstructor functions for primitive arrays: float-array, int-array, etc.\nType hints for primitive arrays - ^ints, ^floats, etc.\nCoercion ops int, float, etc. produce primitives when consumer can take primitive\nThe num coercion function boxes primitives to force generic arithmetic\nArray cast functions ints longs, etc. which produce int[], long[], etc.\nA set of \"unchecked\" operations for utmost performing, but potentially unsafe, integer (int/long) ops: unchecked-multiply unchecked-dec unchecked-inc unchecked-negate unchecked-add unchecked-subtract unchecked-remainder unchecked-divide\nA dynamic var to automatically swap safe operations with unchecked operations: *unchecked-math*\namap and areduce macros for functionally (i.e. non-destructively) processing one or more arrays in order to produce a new array or aggregate value respectively.\n</code></pre> <p>Rather than write this Java:</p> <p>static public float asum(float[] xs){   float ret = 0;   for(int i = 0; i &lt; xs.length; i++)     ret += xs[i];   return ret; }</p> <p>you can write this Clojure:</p> <p>(defn asum [^floats xs]   (areduce xs i ret (float 0)     (+ ret (aget xs i))))</p> <p>and the resulting code is exactly the same speed (when run with java -server).</p> <p>The best aspect of this is that you need not do anything special in your initial coding. Quite often these optimizations are unneeded. Should a bit of code be a bottleneck, you can speed it up with minor adornment:</p> <p>(defn foo [n]   (loop [i 0]     (if (&lt; i n)       (recur (inc i))       i)))</p> <p>(time (foo 100000)) \"Elapsed time: 0.391 msecs\" 100000</p> <p>(defn foo2 [n]   (let [n (int n)]     (loop [i (int 0)]       (if (&lt; i n)         (recur (inc i))         i))))</p> <p>(time (foo2 100000)) \"Elapsed time: 0.084 msecs\" 100000</p> <p>Coercions At times it is necessary to have a value of a particular primitive type. These coercion functions yield a value of the indicated type as long as such a coercion is possible: bigdec bigint boolean byte char double float int long num short</p> <p>Some optimization tips</p> <pre><code>All arguments are passed to Clojure fns as objects, so there's no point to putting non-array primitive type hints on fn args. Instead, use the let technique shown to place args in primitive locals if they need to participate in primitive arithmetic in the body.\n(let [foo (int bar)] ...) is the correct way to get a primitive local. Do not use ^Integer etc.\nDon't rush to unchecked math unless you want truncating operations. HotSpot does a good job at optimizing the overflow check, which will yield an exception instead of silent truncation. On a typical example, that has about a 5% difference in speed - well worth it. Also, people reading your code don't know if you are using unchecked for truncation or performance - best to reserve it for the former and comment if the latter.\nThere's usually no point in trying to optimize an outer loop, in fact it can hurt you as you'll be representing things as primitives which just have to be re-boxed in order to become args to the inner call. The only exception is reflection warnings - you must get rid of them in any code that gets called frequently.\nAlmost every time someone presents something they are trying to optimize with hints, the faster version has far fewer hints than the original. If a hint doesn't improve things in the end - take it out.\nMany people seem to presume only the unchecked- ops do primitive arithmetic - not so. When the args are primitive locals, regular + and * etc do primitive math with an overflow check - fast and safe.\nSo, the simplest route to fast math is to leave the operators alone and just make sure the source literals and locals are primitive. Arithmetic on primitives yields primitives. If you've got a loop (which you probably do if you need to optimize) make sure the loop locals are primitives first - then if you accidentally are producing a boxed intermediate result you'll get an error on recur. Don't solve that error by coercing your intermediate result, instead, figure out what argument or local is not primitive.\n</code></pre> <p>Simple XML Support Included with the distribution is simple XML support, found in the src/xml.clj file. All names from this file are in the xml namespace.</p> <p>(parse source) Parses and loads the source, which can be a File, InputStream or String naming a URI. Returns a tree of the xml/element struct-map, which has the keys :tag, :attrs, and :content. and accessor fns tag, attrs, and content.</p> <p>(xml/parse \"/Users/rich/dev/clojure/build.xml\") -&gt; {:tag :project, :attrs {:name \"clojure\", :default \"jar\"}, :content [{:tag :description, ...</p> <p>Calling Clojure From Java The clojure.java.api package provides a minimal interface to bootstrap Clojure access from other JVM languages. It does this by providing:</p> <ol> <li>The ability to use Clojure's namespaces to locate an arbitrary var, returning the var's clojure.lang.IFn interface.</li> <li>A convenience method read for reading data using Clojure's edn reader</li> </ol> <p>IFns provide complete access to Clojure's APIs. You can also access any other library written in Clojure, after adding either its source or compiled form to the classpath.</p> <p>The public Java API for Clojure consists of the following classes and interfaces:</p> <pre><code>clojure.java.api.Clojure\nclojure.lang.IFn\n</code></pre> <p>All other Java classes should be treated as implementation details, and applications should avoid relying on them.</p> <p>To lookup and call a Clojure function:</p> <p>IFn plus = Clojure.var(\"clojure.core\", \"+\"); plus.invoke(1, 2);</p> <p>Functions in clojure.core are automatically loaded. Other namespaces can be loaded via require:</p> <p>IFn require = Clojure.var(\"clojure.core\", \"require\"); require.invoke(Clojure.read(\"clojure.set\"));</p> <p>IFns can be passed to higher order functions, e.g. the example below passes plus to read:</p> <p>IFn map = Clojure.var(\"clojure.core\", \"map\"); IFn inc = Clojure.var(\"clojure.core\", \"inc\"); map.invoke(inc, Clojure.read(\"[1 2 3]\"));</p> <p>Most IFns in Clojure refer to functions. A few, however, refer to non-function data values. To access these, use deref instead of fn:</p> <p>IFn printLength = Clojure.var(\"clojure.core\", \"print-length\"); IFn deref = Clojure.var(\"clojure.core\", \"deref\"); deref.invoke(printLength);</p>"},{"location":"reference/clojure-syntax/naming/","title":"Naming","text":""},{"location":"reference/clojure-syntax/naming/#naming-when-requiring-other-namespaces","title":"Naming when requiring other namespaces","text":"<p><code>(require [cheshire.core :refer :all])</code> is an example of self-inflicted errors, as this library included a <code>contains?</code> function that will over-write the <code>clojure.core/contains?</code> function when using <code>:refer :all</code> or the <code>(use )</code> expression.</p> <p>This situation is one example of why <code>:refer :all</code> and <code>use</code> are not recommended and can cause lots of debugging headaches.</p> <p>If a namespace is predominantly about using a specific library, then refer specific functions as they are used within the current namespace</p> <pre><code>(ns current.namespace\n(:require\n  [cheshire.core :refer [function-name another-function etc]))\n</code></pre> <p>A classic example is a test namespace that uses clojure core (ns practicalli.random-function-test   (:require [clojure.test :refer [deftest is testing]]             [practicalli.random-function :as sut])) Otherwise use a meaningful alias, ideally referring to what that library is doing (which makes it easer to swap out with a different library later on if required).  As Cheshire is a JSON related library, then (ns my.ns   (:require [cheshire.core :as json])) This gives a context to all the functions called from that library and makes code easier for humans to understand.</p>"},{"location":"reference/clojure-syntax/naming/#hintclj-kondo-lint-tool-shows-unused-functions","title":"Hint::clj-kondo lint tool shows unused functions","text":"<p>Using clj-kondo</p>"},{"location":"reference/clojure-syntax/numbers-maths/","title":"Maths","text":"<p>Fixme Split this into sections ?</p> <p>Writing some simple mathematics helps you get used to the form of Clojure.  Unlike other languages, Clojure does not have operators for mathematics.  Instead <code>+ - * /</code> are all functions in their own right.</p> <p>As Clojure uses pre-fix notation then mathematical expressions are always unambiguous.  There is no need for an operator precedence table in Clojure.</p> <p>Note Write some simple math to help you get used to the form of Clojure</p> <pre><code>(+ 1 2 3 4 5 6 7)\n(- 2 1)\n(* 3 7)\n(/ 12 4)\n(/ 500 20)\n(+ 1 1 2489 459 2.)\n(+ 1 2 (* 3 4) (- 5 6 -7))\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/numbers-maths/#variable-numbers-of-arguments","title":"Variable numbers of arguments","text":"<p>Mathematic functions show the flexibility of Clojure, as they take a variable number of arguments (variadic functions).  Its common for Clojure functions to have zero, one or many arguments (many arguments typically represented as a built-in data structure (map, vector, set or list)</p> <p>Note Write some more maths to show the variadic nature of mathematic (and manu other) functions</p> <pre><code>(+)\n(*)\n(* 2)\n(+ 4)\n\n(+ 1 2 3)\n(&lt; 1 2 3)\n(&lt; 1 3 8 4)\n</code></pre> <p></p> <p>Note Explore some number related functions</p> <pre><code>(rem 22 7)\n(mod 20 12)\n(quot 13 4)\n\n(inc 3)\n(dec 4)\n\n(min 1 2 3 5 8 13)\n(max 1 2 3 5 8 13)\n\n(repeat 4 9)\n\n(range 10)\n(range 18 66)\n(range 2 99 2)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#equality","title":"Equality","text":"<p>Equality is represented by the <code>=</code> function.  Yes, <code>=</code> is a proper function too, not just an operator as with other languages.</p> <p>Note Explore what equality means in Clojure.  Equality is very useful when your data structures are immutable</p> <pre><code>(= 1 1)\n(= 2 1)\n\n(identical? \"foo\" \"bar\")\n(identical? \"foo\" \"foo\")\n(= \"foo\" \"bar\")\n(= \"foo\" \"foo\")\n\n(identical? :foo :bar)\n(identical? :foo :foo)\n\n(true)\n(false)\n(not true)\n(true? (= 1 1))\n(false (= 1 -1))\n</code></pre> <p>Equality is very efficient when your data structures are immutable.  For example if you have very large data sets, you can simply compare a hash value to see if those data structures are the same.</p> <p>Of course you also have the <code>not</code> function for reversing logic too</p> <pre><code>(not true)\n\n=&gt; false\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#boolean-true-and-false","title":"Boolean - True and False","text":"<p>;; some truthiness with math functions for you to try</p> <pre><code>(+)\n(class (+))\n(*)\n(true? +)\n(false? +)\n(true? *)\n(false? *)\n(true? 1)\n(true? -1)\n(true? true)\n(- 2)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#boolean-predicates","title":"Boolean &amp; Predicates","text":"<p>Predicates are functions that take a value and return a boolean result (true | false)</p> <pre><code>(true? true)\n(true? (not true))\n(true? false)\n(true? (not false))\n(true? nil)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#types","title":"Types","text":"<p>Clojure uses Java's object types for booleans, strings and numbers.  Use the <code>class</code> function to inspect them.</p> <pre><code>(class 1)\n; Integer literals are java.lang.Long by default\n(class 1.1)    ; Float literals are java.lang.Double\n\n(class \"\")\n; Strings always double-quoted, and are java.lang.String\n\n(class false)  ; Booleans are java.lang.Boolean\n(class nil)    ; The \"null\" value is called nil\n\n(class (list 1 2 3 4))\n\n\n(class true)\n(class ())\n(class (list 1 2 34 5))\n(class (str 2 3 4 5))\n(class (+ 22/7))\n(class 5)\n(class \"fish\")\n(type [1 2 3])\n(type {:a 1 :b 2})\n\n(type (take 3 (range 10)))\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#ratios","title":"Ratios","text":"<p>To help maintain the precision of numbers, Clojure has a type called Ratio.  So when you are dividing numbers you can keep the as a fraction using whole numbers, rather than constrain the result to a approximate</p> <pre><code>(/ 2)\n</code></pre> <p>A classic example is dividing 22 by 7 which is approximately the value of Pi</p> <pre><code>(/ 22 7)\n\n(class (/ 22 7))\n</code></pre> <p>If you want to force Clojure to evaluate this then you can specify one of the numbers with a decimal point</p> <pre><code>(class (/ 22 7.0))\n</code></pre>"},{"location":"reference/clojure-syntax/parenthesis/","title":"Parenthesis - defining the structure of Clojure code","text":"<p>Clojure uses parenthesis, round brackets <code>()</code>, as a simple way to define the structure of the code and provide clear and unambiguous scope.  This structure is the syntax of symbolic expressions.</p> <p></p> <p>Parenthesis, or parens for short, are used to define and call functions in our code, include libraries and in fact any behavior we wish to express.</p> <p>Clojure includes 3 other bracket types to specifically identify data: <code>'()</code> quoted lists and sequences, <code>[]</code> for vectors (arrays) and argument lists, <code>{}</code> for hash-maps and <code>#{}</code> for sets of data.</p> <p>No other terminators or precedence rules are required to understand how to read and write Clojure.</p>"},{"location":"reference/clojure-syntax/parenthesis/#the-parenthesis-hangup","title":"The Parenthesis hangup","text":"<p>Some raise the concern that there are \"too many brackets\" in Clojure.</p> <p>Clojure doesn't require any additional parens compared to other languages, it simply moves the open parens to the start of the expression giving a clearly defined structure to the code</p> <p>With support for higher order functions, functional composition and threading macros, Clojure code typically uses fewer parens than other languages especially as the scope of the problem space grows.</p> <p>All languages use parens to wrap a part of an expression, requiring additional syntax to identify the boundaries of each expression so it can be parsed by humans and computers alike.  Clojure uses a single way to express everything, homoiconicity, where as most other languages require additional syntax for different parts of the code.</p> <p>Using parens, Clojure has a well defined structure that provides a clearly defined scope to every part of the code.  There is no requirement to remember a long list of ad-hoc precedence rules, e.g. JavaScript operator precedence.</p> <p>This structure of Clojure code is simple to parse for both humans and computers.  it is simple to navigate, simple to avoid breaking the syntax of the language and simple to provide tooling that keeps the syntax of the code correct.</p> <p>After realising the simplicity that parens bring, you have to wonder why other (non-lisp) languages made their syntax more complex.</p>"},{"location":"reference/clojure-syntax/parenthesis/#working-with-parens","title":"Working with Parens","text":"<p>Clojure aware editors all support structured editing to manage parens and ensure they remain balanced (same number of open and close parens).</p> <p>A developer only needs to type the open paren and the editor will automatically add the closing paren.</p> <p>Parens cannot be deleted unless their content is empty.</p> <p>Code can be pulled into parens (slurp) or pushed out of parens (barf).  Code can be split, joined, wrapped, unwrapped, transposed, convoluted and raised, all without breaking the structure.</p> <ul> <li>Smartparens for Structural editing - a modern update of ParEdit</li> <li>The animated guide to ParEdit</li> </ul>"},{"location":"reference/clojure-syntax/parenthesis/#homoiconicity-and-macros","title":"Homoiconicity and Macros","text":"<p>Clojure is a dialect of LISP and naturally was designed to be a homoiconic language. This means the syntax for behavior and data is the same.  This greatly simplifies the syntax of Clojure and all LISP style languages.</p> <p>The Clojure Reader is a parser that reads in data structures as expression, rather than parsing of text required by other languages. The result of parsing is a collection of data structures that can be traversed (asymmetric syntax tree - AST).  Compared to most languages the compiler does very little and you can consider Clojure really does not have a syntax.</p> <p>Code is written as data structures that are accessible to the other parts of the code, providing a way to write code that manipulate those data structures and generate new code. In Clojure this type of code is called a macro, a piece of code that writes new code.</p> <p></p> <p>None of this would work as simply as it does without using parens and the symbolic expression syntax.</p> <ul> <li>Inspired by Beating the Averages by Paul Graham</li> </ul>"},{"location":"reference/clojure-syntax/parenthesis/#example-function-invocation","title":"Example: Function invocation","text":"<p>The choice was made early in the design of Lisp that lists would be used for function invocation in the form:</p> <pre><code>(function arg1 arg2 arg3)\n;; =&gt; value returned\n</code></pre> <p>The advantages of this design are:</p> <ul> <li>a function call is just one expression, called a \"form\"</li> <li>function calls can be constructed  (cons function-symbol list-of-args)</li> <li>functions can be arguments to other functions (higher order functions)</li> <li>simple syntax to parse - everything between two parentheses is a self-contained expression.</li> <li>fewer parens due to high order functions, composition and threading macros</li> </ul> <p>The function name could have been put outside the parentheses:</p> <pre><code>function (arg1 arg2 arg3) =&gt; some result\n</code></pre> <p>This design has many disadvantages:</p> <ul> <li>a function call is no longer a single form and have to pass the function name and the argument list.</li> <li>syntax is complex and requires additional syntax rules to define a function call</li> <li>code generation is very complex</li> <li>same number of parens as Clojure or possibly more (no direct support for higher order functions)</li> </ul>"},{"location":"reference/clojure-syntax/private-functions/","title":"Private functions","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/quick-look-at-types/","title":"A quick look at types","text":"<p>As we mentioned before, underneath Clojure lurks Java byte code so there are going to be types in Clojure.  However, Clojure being a dynamic language, most of the time you can just let Clojure manage the types for you.</p> <p>Hint When you run Clojure on a different host platform, eg. .Net or Javascript (via Clojurescript), Clojure will use the types of that host platform.</p> <p>Should you want to know the type of something you are working on, you can use two functions, <code>type</code> and <code>class</code>.</p> <p>Note Discover the class or type of some common Clojure code</p> <pre><code>(class 1)\n(class 1.1)\n(class \"\")\n(class true)\n(class false)\n(class nil)\n\n(class ())\n(class (list 1 2 3 4))\n(class (str 2 3 4 5))\n(class (+ 22/7))\n\n(type [1 2 3])\n(type {:a 1 :b 2})\n(type (take 3 (range 10)))\n</code></pre> <p></p> <p>Hint If you cant live without static type checking, look at core.typed, a type system for Clojure all in one library</p>"},{"location":"reference/clojure-syntax/ratios/","title":"Ratios","text":"<p>In mathematics you need to ensure that you manage precision of your calculations when you are dividing numbers.  Once you create a decimal number then everything it touches had a greater potential to becoming a decimal.</p> <p>Note Calculate a rough approximation to Pi by dividing 22 by 7</p> <pre><code>(/ 22 7)\n(class (/ 22 7))\n(/ (* 22/7 3) 3)\n</code></pre> <p></p> <p>If the result of an integer calculation would be a decimal number, then Clojure holds the value as a Ratio.  This is one example of lazy evaluation.  Rather than calculate the decimal value at some particular precision (number of decimal points).  Clojure is saving the calculation until its needed, at which time the specific precision required should be known.</p> <p>Note Explore the ratio type further and see how to get a decimal value as the result</p> <pre><code>(/ 14 4)\n(/ 16 12)\n(/ 2)\n(/ 22 7.0)\n(type (/ 22 7.0))\n(float (/ 22 7))\n(double (/ 22 7))\n</code></pre> <p></p> <p>When one or more of the numbers in the division is a decimal, then Clojure will return a decimal value.  Or you can coerce a value to a specific decimal type, eg. float or double.</p>"},{"location":"reference/clojure-syntax/strings/","title":"Strings","text":"<p>Strings in Clojure are actually Java Strings.</p> <p>Hint  Why do you think this design decision was taken for Clojure?</p> <p>If you think about the state property of String objects, then you realise that String Objects are immutable and cannot be changed.  As this is the default approach for other data structures and values in Clojure it makes sense to use Java Strings instead of writing a Clojure implementation.</p> <p>As Clojure strings are Java strings, then you can use all the same functions you can in Java.</p> <p>Note Use the Java function <code>println</code> to output a string</p> <pre><code>(println \"Hello, whats different with me?  What value do I return\")\n</code></pre> <p></p> <p>Something different happens when you evaluate this expression.  The actual value returned is <code>nil</code>, not the string.  You see the string because println is writing to the console (i.e the REPL).</p> <p>Hint Avoid code that creates side-effects where possible to keep your software less complex to understand.</p> <p>You may be used to using println statements to help you debug your code, however, with the fast feedback you get from developing in the REPL then there is usually no need for them.</p>"},{"location":"reference/clojure-syntax/strings/#strings-the-clojure-way","title":"Strings the Clojure way","text":"<p>Its more common to use the <code>str</code> function when working with strings, as this function returns the string as its. value when evaluated.</p> <p>(str \"Hello, I am returned as a value of this expression\")</p> <p>Note Join strings together with the function str</p> <pre><code>(str \"I\" \"like\" \"to\" \"be\" \"close\" \"together\"\n(str \"Hello\" \", \" \"Devoxx UK\")\n(str \"Hello \"  \"developers\" \", \" \"welcome\" \" \" \"to\" \" \" \"HackTheTower UK\")\n</code></pre> <p>You can see that there are no side-effects when using <code>str</code> and the string is returned as the value of the function call.</p>"},{"location":"reference/clojure-syntax/strings/#using-interpose-with-strings","title":"Using Interpose with Strings","text":"<p>Its easy to join strings together with the <code>str</code> function, however <code>str</code> leaves no spaces between words.</p>"},{"location":"reference/clojure-syntax/strings/#using-regex","title":"Using Regex","text":""},{"location":"reference/clojure-syntax/strings/#java-interop-for-strings","title":"Java Interop for Strings","text":"<p>Note Change the case of strings and other common actions using the String object methods, in the form <code>(.methodName object)</code></p> <pre><code>(.toUpperCase \"show me the money\")\n\n(.getName String)\n\n(.indexOf \"Where is the $ in this string\" \"$\")\n</code></pre> <p>Hint Look at the API docs for java.lang.String for other methods you can call.</p>"},{"location":"reference/clojure-syntax/syntax/","title":"Clojure syntax","text":"<p>Clojure is perceived as having an abundance of <code>()</code>, the symbols that represent a list.</p> <p>As Clojure is a LISP (List Processing) language then everything is written in the form of a list.  This makes Clojure very powerful and also easier to read.</p> <p>Using a list structure also demonstrates the data-centric nature of Clojure.  Every item in the list has a value, with the first item evaluated by a function call.</p>"},{"location":"reference/clojure-syntax/syntax/#hintparens-everywhere","title":"Hint::Parens everywhere","text":"<p>The seemingly abundance of <code>()</code> can be confusing until its realized there are fewer \"special characters\" in Clojure than other languages.  Clojure aware editors support matching parens, adding a closed paren when typing an open paren, ensuring it is easy to write correctly formed Clojure.</p> <p>Syntax differences are a trivial reason to avoid trying Clojure.  Syntax aware editors significantly reduce typing by automatically closing parenthesis and eliminating errors due to missing delimiters (ie. no more errors due to missing ; in C-based languages)</p>"},{"location":"reference/clojure-syntax/syntax/#prefix-notation","title":"Prefix notation","text":"<p>Instead of having a mix of notations like in many other languages, Clojure uses pre-fix notation entirely.</p> <p>In Clojure operators are applied uniformly and there is no room for ambiguity:</p> <pre><code>    (+ 1 2 3 5 8 13 21)\n    (+ 1 2 (- 4 1) 5 (* 2 4) 13 (/ 42 2))\n    (str \"Clojure\" \" uses \" \"prefix notation\")\n</code></pre> <p>In Java and other C-based languages you have to explicitly add operators everywhere and there can be a mixture of notations</p> <pre><code>    (1 + 2 + 3 + 5 + 8 + 13 + 21);\n    (1 + 2 + (- 4 1) + 5 + (* 2 4) + 13 + (/ 42 2));\n    StringBuffer description = new StringBuffer(\"C-based languages\" + \" mix \" + \"notation\");\n    x+=1;\n    x++;\n    x--;\n    x+=y;\n    x-=y;\n    x*=y;\n    x/=y;\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#references","title":"References","text":"<ul> <li>Clojure Style Guide</li> </ul>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/","title":"Threading Syntax Sugar","text":"<p>The previous code is written in classic Lisp style.  When you come to read Lisp, you start from the inside out.  In this case you start with <code>(slurp ...)</code> and what it returns is used as the argument to <code>(read-string ...)</code> and so on...</p> <p>In our minds we probably constructed the following basic algorithm:</p> <ul> <li>Get the contents of the project.clj file using <code>slurp</code></li> <li>Read the text of that file using read-string</li> <li>Select just the third string using nth 2 (using an index starting at 0)</li> </ul> <p>Can we rewrite our Clojure code to fit the way we think?</p>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#thread-first-macro","title":"Thread first macro","text":"<p>Using the thread-first macro -&gt; we can chain Clojure functions together with a terser syntax, passing the result of the first evaluation as the first argument to the next function and so on.  Using this style, we can write code that matches the algorithm in our head.</p> <p>To make this really simple lets create a contrived example of the threading macro.  Here we use the <code>str</code> function to join strings together.  Each individual <code>str</code> function joins its own strings together, passing the resulting string as the first argument to the next function.</p> <pre><code>(-&gt;\n (str \"This\" \" \" \"is\" \" \")\n (str \"the\" \" \" \"threading\" \" \" \"macro\")\n (str \"in\" \" \" \"action.\"))\n\n;; =&gt; \"This is the threading macro in action\"\n</code></pre>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#thread-last-macro","title":"Thread-last macro","text":"<p>Using the thread-last macro, -&gt;&gt;, the result of a function is passed as the last argument of the next function call.  So in another simple series of str function calls, our text comes out backwards.</p> <pre><code>(-&gt;&gt;\n (str \" This\")\n (str \" is\")\n (str \" backwards\"))\n\n;; =&gt; backwards is This\"\n</code></pre>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#_1","title":"Threading Syntax Sugar","text":"<p>Note Refactor the Clojure code using the thread-first macro</p> <pre><code>(-&gt;\n \"./project.clj\"\n slurp\n read-string\n (nth 2))\n</code></pre> <p>Hint The \"project.clj\" is a string, so when you evaluate it as an expression, it simply returns the same string.  That string is then passed as an argument to any following functions.</p> <p>Using the threading macro, the result of every function is passed onto the next function in the list.  This can be seen very clearly using ,,, to denote where the value is passed to the next function</p> <pre><code>(-&gt;\n \"project.clj\"\n slurp ,,,\n read-string ,,,\n (nth ,,, 2))\n</code></pre> <p>Hint Commas in clojure are treated as whitespace, they are simply ignored when it comes to evaluating code.  Typically commas are rarely used and only to help human readability of the code</p> <p>Note Create a new map that contains the project configuration for the current project</p> <pre><code>(-&gt;&gt; \"project.clj\"\n     slurp\n     read-string\n     (drop 2)\n     (cons :version)\n     (apply hash-map)\n     (def project-configs))\n\n;; Evaluate the new map defined as project\nproject\n</code></pre> <p>We pull out the map of project information using <code>slurp</code>, tidy the text up using <code>read-string</code> and drop the first two elements (defproject playground).  This returns a list that we want to turn into a map, but first we need to add a key to the version number.  Using the <code>cons</code> function we can add an element to the start of the list, in this case the <code>:version</code> keyword</p> <p>Now we can successfully convert the list that is returned into a map, with balanced key-value pairs.  Then we simply create a name for this new map, <code>project-configs</code>, so we can refer to it elsewhere in the code.</p> <p>Hint The <code>slurp</code> function holds the contents of the whole file in memory, so it may not be appropriate for very large files.  If you are dealing with a large file, consider wrapping slurp in a lazy evaluation or use Java IO (eg. <code>java.io.BufferedReader</code>, <code>java.io.FileReader.</code>).  See the Clojure I/O cookbook and The Ins &amp; Outs of Clojure for examples.</p>"},{"location":"reference/clojure-syntax/whats-my-environment/","title":"Whats my environment","text":"<p>Clojure has symbols (names that point to values).  Some of these symbols are built into the language and their names start (and usually end with) the <code>*</code> character.</p> <p>When symbols are evaluated they return the value that they point to.</p> <p>Note Check the version of Clojure running in your REPL.</p> <p>Enter the following code into the Clojure REPL:</p> <pre><code>*clojure-version*\n</code></pre> <p></p> <p>The full clojure version can be used to check you are running a particular version, major or minor of Clojure core.  This information is represented as a map containing <code>:major</code>, <code>:minor</code>, <code>:incremental</code> and <code>:qualifier</code> keys.    Feature releases may increment :minor and/or :major, bugfix releases will increment :incremental.  Possible values of :qualifier include \"GA\", \"SNAPSHOT\", \"RC-x\" \"BETA-x\"</p> <p>Hint A map in Clojure is a built in data structure represented by <code>{ }</code>. A map is a key-value pair and there must be a value for every key for the map to be valid.  Keys are often defined using <code>:keyword</code>, a self-referential pointer that can be used to look up values in a map or other data structures.</p>"},{"location":"reference/clojure-syntax/whats-my-environment/#viewing-the-class-path","title":"Viewing the Class path","text":"<p>Clojure compiles to Java bytecode that runs on the JVM, so that code needs to be available in the Java class path.</p> <p>Note Look at the class path for your project</p> <p>The directory where the Clojure compiler will create the .class files for the current project.  All .class files must be on the class path otherwise the Clojure run time environment will not know they exist.</p> <pre><code>*compile-path*\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/whats-my-environment/#namespace","title":"Namespace","text":"<p>A namespace in clojure is a way to separate functions and data structures into logical components (similar to Java packages).  A <code>clojure.lang.Namespace</code> object representing the current namespace.</p> <p>Note Find out the current namespace</p> <pre><code>*ns*\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/whats-my-environment/#last-3-values-in-the-repl","title":"Last 3 values in the REPL","text":"<p>You can also get the 3 most most recent values returned in the REPL.</p> <p>Note Evaluate the following three expressions in the REPL, then pull out the last three results</p> <pre><code>(+ 1 2 3)\n\n(+ 1 2 (+ 1 2) (+ 2 3))\n\n(str \"Java will be fully functional in version \" (+ 10 (rand-int 20))\n</code></pre> <p>Now get the last three values returned in the REPL</p> <pre><code>(str *1 *2 *3)\n</code></pre> <p></p> <p>Hint You can cycle through previous expressions entered into the REPL using the <code>Shift-UpArrow</code> keyboard shortcut</p>"},{"location":"reference/clojure-syntax/syntax/","title":"Clojure Syntax","text":"<p>The Clojure syntax is very small and is actually a data structure, defined as a list, <code>()</code>, with the first element of a list being a function call and all other elements arguments to that function.</p> <p>Examples are editable (using an embedded REPL) so feel free to experiment and watch as the return value changes as you change the code. Reload the page if you want to reset all the code back to the starting point.</p>"},{"location":"reference/clojure-syntax/syntax/#edn-based-notation","title":"edn based notation","text":"<p>The core Clojure syntax is defined in the extensible data notation (edn). edn demonstrates that Clojure code is defined as a series of data structures</p> <p>Clojure adds an execution model on top of edn to make a programming language and is a super-set of edn.</p> <p>edn is used as a data transfer format, especially for Datomic the Clojure transactional database</p> <ul> <li>A case for Clojure by James Reeves provides a great introduction to edn</li> </ul>"},{"location":"reference/clojure-syntax/syntax/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is treated as a call to a function. The examples show how to call functions with multiple arguments.</p> <pre><code>(+ 1 2)\n</code></pre> <pre><code>(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n</code></pre> <pre><code>(str \"Clojure is \" (- 2020 2007) \" years old\")\n</code></pre> <pre><code>(inc 1)\n</code></pre> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <pre><code>(filter odd? (range 11))\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintprefix-notation-and-parens","title":"Hint::Prefix notation and parens","text":"<p>Hugging code with <code>()</code> is a simple syntax to define the scope of code expressions.  No additional <code>;</code>, <code>,</code> or spaces are required.</p> <p>Treating the first element of a list as a function call is referred to as prefix notation, which greatly simplifies Clojure syntax.  Prefix notation makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p>"},{"location":"reference/clojure-syntax/syntax/#understanding-functions","title":"Understanding functions","text":"<p>Functions contain doc-strings describing what that function does. The <code>doc</code> function returns the doc-string of a particular function.  Most editors also support viewing of doc-strings as well as jumping to function definitions to view the source code</p> <pre><code>(doc doc)\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#strongly-typed-under-the-covers","title":"Strongly typed under the covers","text":"<p>Clojure is a dynamically typed language so types do not need to be explicitly defined, although type hints can be added for performance where required.</p> <p>Clojure is strongly typed and everything is a type underneath, relative to the host platform (Clojure uses Java types, ClojureScript uses JavaScript types).  The type of anything in Clojure can be returned using the <code>type</code> function.</p> <pre><code>(type 42)\n;; (type {:hash \"data\" :map \"more data\"})\n</code></pre> <pre><code>(type {:hash \"data\" :map \"more data\"})\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <pre><code>(str \"lists used mainly \" (* 2 2) \" \" :code)\n</code></pre> <pre><code>[0 \"indexed\" :array (* 2 2) \"random-access\"]\n</code></pre> <pre><code>{:key \"value\" \"hash-map\" \"also referred to as dictionary\"}\n</code></pre> <pre><code>#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintpersistent-data-types","title":"Hint::Persistent data types","text":"<p>To change data in Clojure new copies are created rather than changing existing values.  The copies of data will share values from the original data that are common in both.  This sharing is called persistent data types and enables immutable data to be used efficiently.</p>"},{"location":"reference/clojure-syntax/syntax/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>Names can be bound to any values, from simple values like numbers, collections or even function calls.  Using <code>def</code> is convenient way to create names for values that are shared in your code.</p> <p>evaluating a name will return the value it is bound to.</p> <pre><code>(def public-health-data\n  ({:date \"2020-01-01\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-03\" :confirmed-cases 23014 :recovery-percent 15}))\n\npublic-health-data\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintdef-for-shared-values-let-for-locally-scoped-values","title":"Hint::def for shared values, let for locally scoped values","text":"<p><code>let</code> function is used to bind names to values locally, such as within a function definition.  Names bound with <code>def</code> have namespace scope so can be used with any code in that namespace.</p>"},{"location":"reference/clojure-syntax/syntax/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p> <p><code>map</code> <code>reduce</code> <code>filter</code> are common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n</code></pre> <pre><code>(filter even? [1 3 5 8 13 21 34])\n</code></pre> <pre><code>(reduce + [31 28 30 31 30 31])\n</code></pre> <pre><code>(empty? [])\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(map (fn [x] (* x x)) [1 2 3 4 5])\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#host-interoperability","title":"Host Interoperability","text":"<p>The REPL in this web page is running inside a JavaScript engine, so JavaScript functions can be used from within ClojureScript code (ClojureScript is Clojure that runs in JavaScript environments).</p> <p>In the box below, replace <code>()</code> with <code>(js/alert \"I am a pop-up alert\")</code></p> <pre><code>()\n</code></pre> <p>JavaScript libraries can be used with ClojureScript, such as React.js</p> <pre><code>(defn concentric-circles []\n  [:svg {:style {:border \"1px solid\"\n                 :background \"white\"\n                 :width \"150px\"\n                 :height \"150px\"}}\n   [:circle {:r 50, :cx 75, :cy 75, :fill \"green\"}]\n   [:circle {:r 25, :cx 75, :cy 75, :fill \"blue\"}]\n   [:path {:stroke-width 12\n           :stroke \"white\"\n           :fill \"none\"\n           :d \"M 30,40 C 100,40 50,110 120,110\"}]\n   [:path {:stroke-width 12\n           :stroke \"white\"\n           :fill \"none\"\n           :d \"M 75,75 C 50,90 50,110 35,110\"}]])\n</code></pre>"},{"location":"reference/jvm/","title":"Reference: Java Virtual Machine","text":"<p>Understand the configuration options for the Java Virtual machine (JVM) which Clojure is hosted upon.</p> <p>Overview of tools for monitoring and profiling Clojure applications running on the JVM, to ensure effective running of Clojure applications in production.</p> <ul> <li>Common JVM Options - for development and deployment</li> <li>JVM Profiling tools - understand resources and help diagnose run-time problems</li> </ul> <p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p>"},{"location":"reference/jvm/#display-resources-available-to-the-jvm","title":"Display resources available to the JVM","text":"<p><code>-XshowSettings:system</code> displays the resources the JVM believes it has access too when running any Java command and is a very simple diagnostic tool to start with.</p> <p>See the environment resources available to the JVM without running a Clojure or Java application:</p> <pre><code>java -XshowSettings:system -version\n</code></pre> <p></p> <p>Include <code>-XshowSettings:system</code> when running any Java command to provide simple diagnostics, e.g. when running a Clojure Uberjar</p> <pre><code>java -XshowSettings:system -jar practicalli-service.jar\n</code></pre> <p>Print resources in Container systems</p> <p><code>-XshowSettings:system</code> is especially useful for environments which may vary in resources available, such as containers (Docker, Kubernettes, etc.)</p>"},{"location":"reference/jvm/#jvm-option-types","title":"JVM option types","text":"<p><code>-X</code> - nonstandard VM options</p> <p><code>-XX</code> standard VM options</p> <p><code>-XX</code> options are not checked for validity, so are ignored if the VM does not recognize the option. Options can therefore be used across different VM versions without ensuring a particular level of the VM.</p> <p><code>-D</code> a system property for the application running on the JVM using a name=value</p>"},{"location":"reference/jvm/#java-modules","title":"Java Modules","text":"<p>Java 9 introduced modules to move features out of JVM itself and include them as optional modules.</p> <p>Before CLJS-2377 issue was resolved, ClojureScript (2017) depended on <code>java.xml.bind.DataTypeConverter</code>. <code>java.xml.bind package</code> was deprecated in Java 9 and moved to a non-default module.</p> <p>At that time, compiling a ClojureScript project without adding the java.xml.bind module would return the error:</p> <pre><code>&lt;Exception details&gt;\n...\nCaused by: java.lang.ClassNotFoundException: javax.xml.bind.DatatypeConverter\n</code></pre> <p><code>clojure J--add-modules \"java.xml.bind\"</code> command line option will include the module</p> <p><code>:jvm-opts [\"--add-modules\" \"java.xml.bind\"]</code> added to Clojure CLI deps.edn or Leiningen project.clj file will include the module.</p> <p><code>-Djdk.launcher.addmods=java.xml.bind</code> added to the <code>JAVA_TOOL_OPTIONS</code> environment variable (<code>jdk.launcher.addmods</code> <code>--add-modules</code> doesn\u2019t work in <code>JAVA_TOOL_OPTIONS</code>)</p>"},{"location":"reference/jvm/#unified-logging-sub-system","title":"Unified Logging sub-system","text":"<p><code>-Xlog</code> - JEP 158</p>"},{"location":"reference/jvm/#references","title":"References","text":"<ul> <li>Best practice for JVM Tuning with G1 GC</li> <li>Command Line Options - IBM SDK documentation</li> <li>Best HotSpot JVM Options and switches for Java 11 through Java 17</li> </ul>"},{"location":"reference/jvm/common-options/","title":"Common JVM Options","text":"<p>Examples of commonly used options for any language on the Java Virtual Machine (JVM).</p> <p>The JVM is excellent at self-optimising its performance.  Introducing specific options should only be done if specific resource or performance issues have been identified.</p> <p>Understanding memory usage has more options to diagnose out of memory errors, garbage collection pauses and JIT compilation</p> <p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p>"},{"location":"reference/jvm/common-options/#java-heap-size","title":"Java heap size","text":"<p>Java Ergonomics should provide sensible default options.  Performance analysis of the running code may show advantages of manually setting memory sizes.</p> <p>Set the initial heap size if memory usage will quickly grow</p> <p><code>-Xms</code> \u2013 start heap size for JVM, e.g. <code>-Xms2048m</code> sets an initial heap size of 2 GB</p> <p><code>-XX:InitialRAMPercentage=n</code> sets the initial heap as <code>n</code> percentage of total RAM</p> <p>Set the maximum heap size if usage is relatively high under normal conditions</p> <p><code>-Xmx</code> \u2013 maximum heap size of JVM, e.g. <code>-Xmx2048m</code></p> <p><code>-XX:MaxRAMPercentage=n</code> sets the maximum heap as <code>n</code> percentage of total RAM</p> <p><code>-Xss</code> - set java thread stack size</p> <p><code>-Xms</code> and <code>-Xmx</code> are commonly used together (where there is a know fixed value for memory resources).</p>"},{"location":"reference/jvm/common-options/#heap-and-garbage-collection","title":"Heap and garbage collection","text":"<p><code>-XX:MaxHeapFreeRatio</code> \u2013 maximum percentage of heap free after garbage collection to avoid shrinking.</p> <p><code>-XX:MinHeapFreeRatio</code> \u2013 minimum percentage of heap free after GC to avoid expansion</p> <p>VisualVM or JConsole can monitor the heap usage</p>"},{"location":"reference/jvm/common-options/#container-environments","title":"Container Environments","text":"<p><code>-XX:InitialRAMPercentage</code> and <code>-XX:MaxRAMPercentage</code> options should be used to set relative limits to the resources available from the host.</p> <p>Setting specific heap sizes with <code>-Xms</code> and <code>-Xmx</code> is strongly discouraged in Container environments, as resources available to the container from the host could change between deployments (e.g. a change in operational configuration in Kubernettes, etc.)</p>"},{"location":"reference/jvm/common-options/#stack-traces","title":"Stack traces","text":"<p><code>-XX:-OmitStackTraceInFastThrow</code> no StackTrace for implicit exceptions thrown by JVM, e.g. NullPointerException, ArithmeticException, ArrayIndexOutOfBoundsException, ArrayStoreException or ClassCastException.</p>"},{"location":"reference/jvm/common-options/#reflection","title":"Reflection","text":"<p><code>--illegal-access</code> option controls how deep reflection warnings are handled.</p> <ul> <li>permit (default) - generates warning only when the first illegal access was detected</li> <li>warn - emit warning after each illegal access detection</li> <li>debug - add stack trace to warning</li> <li>deny - like debug for the first detection, then killing the program.</li> </ul> <p>Java 16 deprecates <code>--illegal-access</code> flag, via work done for JEP403 - may still be useful for 3rd party Java libraries.</p>"},{"location":"reference/jvm/common-options/#enable-class-data-sharing","title":"Enable class data sharing","text":"<p><code>-Xshareclasses</code> enables class data sharing in a shared class cache.</p> <p>The JVM connects to an existing cache (creating a cache if none exist). Multiple caches specified by adding a sub-option to the <code>-Xshareclasses</code> option.</p>"},{"location":"reference/jvm/common-options/#handling-outofmemory-error","title":"Handling \u2018OutOfMemory\u2019 Error","text":"<p>Generating a Heap Dump for out of memory (OOM) issues is recommended for production systems, to provide data for a deep analysis of the problem.  Generating a heap dump does not add overhead to the running JVM.</p> <p><code>-XX:+HeapDumpOnOutOfMemoryError</code> - trigger heap dump on out of memory failure</p> <p><code>-XX:HeapDumpPath=path-to-heap-dump-directory</code> - sets path to write the heap dump file (defaults to directory in which java command was ran from)</p> <p>A heap dump file can gigabytes in size, so assure that the target file system has sufficient capacity.</p> <p><code>-XX:OnOutOfMemoryError=\"shutdown -r\"</code> - restart the process immediately after out of memory failure</p> <p>The option can take multiple commands, separated by a <code>;</code>, e.g. <code>-XX:OnOutOfMemoryError=\"&lt; cmd args &gt;;&lt; cmd args &gt;\"</code></p>"},{"location":"reference/jvm/common-options/#trace-classloading-and-unloading","title":"Trace classloading and unloading","text":"<p>Identify memory leaks suspected from the JVM Class Loader, e.g. classes are not unloading or garbage collected</p> <p><code>-XX:+TraceClassLoading</code>  - log classes loaded into the JVM</p> <p><code>-XX:+TraceClassUnloading</code> - log classes unloaded from the JVM</p>"},{"location":"reference/jvm/common-options/#profiling","title":"Profiling","text":"<p>Profiling JVM processes provides a fine-grained view of application execution and resource utilization. Monitor parameters including Method Executions, Thread Executions, Garbage Collections and Object Creations.</p> <ul> <li><code>-Xprof</code></li> <li><code>-Xrunhprof</code></li> </ul> <p>Consider using a profile tool, such as VisualVM</p> <p></p>"},{"location":"reference/jvm/common-options/#skip-byte-code-verification","title":"Skip byte code verification","text":"<p>The byte code for each class loaded by the JVM Class Loader is verified, which is a relatively expensive task at startup. Adding classes on the boot classpath skips the cost of the verification, although also introduces a security risk so should only be used when classes have been previously verified.</p> <ul> <li><code>-Xbootclasspath</code> specifies classpath entries to load without verification</li> </ul> <p>Profiling an application is a more suitable long term solution than skipping byte code verification</p> <p>Checks carried out by the verifier include</p> <ul> <li>Uninitialized Variables</li> <li>Access rules for private data and methods are not violated</li> <li>Method calls match the object Reference</li> <li>There are no operand stack overflows or under-flows</li> <li>Arguments to all JVM instructions are valid types</li> <li>Final classes are not subclassed and final methods are not overridden</li> <li>field and method references have valid names, valid classes and valid type descriptor</li> </ul>"},{"location":"reference/jvm/common-options/#print-gc","title":"Print GC","text":"<p>Enable the garbage collection logging to capture detailed statistics, e.g. type of garbage collector, how often memory is restored and how much time memory was held for. Garbage collection can last several milliseconds, so logging is useful for latency-sensitive processes.</p> <ul> <li><code>-verbose:gc</code> - logs garbage collector runs and how long they're taking.</li> <li><code>-XX:+PrintGCDetails</code> - includes the data from -verbose:gc but also adds information about the size of the new generation and more accurate timings.</li> <li><code>-XX:-PrintGCTimeStamps</code> - Print timestamps at garbage collection.</li> </ul> <p>Consider using LMAX disruptor for a Garbage Collection free architecture for ultra latency-sensitive applications</p>"},{"location":"reference/jvm/common-options/#deprecated-permgen-size","title":"Deprecated: PermGen Size","text":"<p><code>-XX:PermSize</code> - size of PermGen space where string pool and class metadata is saved.</p> <p>Option is useful for web servers which load classes of a web application during deployment (e.g. deploying a jar or war to Tomcat).</p> <p>Metaspace has taken over PermGen space in Java 8 onward</p>"},{"location":"reference/jvm/experimental-options/","title":"Reference: JVM Experimental Options","text":"<p>The HotSpot JVM provides the opportunity to try features that may appear in future release, although are currently not production-ready.</p> <p>HotSpot JVM experimental features need to be unlocked by specifying the <code>-XX:+UnlockExperimentalVMOptions</code> option.</p> <p>For example, the ZGC garbage collector in JDK 11 can be accessed using</p> <pre><code>java -XX:+UnlockExperimentalVMOptions -XX:+UseZGC\n</code></pre> <p>The ZGC collector became a product option in JDK 15, so is no longer experimental.</p>"},{"location":"reference/jvm/experimental-options/#manageable","title":"Manageable","text":"<p>Show locks held by <code>java.util.concurrent</code> classes in a HotSpot JVM thread dump:</p> <pre><code>java -XX:+UnlockExperimentalVMOptions -XX:+PrintConcurrentLocks\n</code></pre> <p>These options can be set at runtime via the MXBean API or related JDK tools</p>"},{"location":"reference/jvm/experimental-options/#diagnostic","title":"Diagnostic","text":"<p>Accessing advanced diagnostic information about the HotSpot JVM.</p> <p>These options require you to use the <code>-XX:+UnlockDiagnosticVMOptions</code>  option before they can be used.</p> <p>View advance compilation optimisations using the <code>-XX:+LogCompilation</code> option:</p> <pre><code>java -XX:+UnlockDiagnosticVMOptions -XX:+LogCompilation\n</code></pre> <p>The HotSpot JVM outputs a log file containing details of all the optimisations made by the JIT compilers. Inspect the output to understand which parts of your program were optimized and to identify parts of the program that might not have been optimized as expected.</p> <p>The LogCompilation output is verbose but can be visualized in a tool such as JITWatch, which can tell you about method inlining, escape analysis, lock elision, and other optimizations that the HotSpot JVM made to your running code.</p>"},{"location":"reference/jvm/java-17-flags/","title":"Reference: Java 17 JVM flags","text":"<p>A complete list of all flags available for the JVM, created using the <code>-XX:+PrintFlagsFinal</code> option and the results written to a file</p> <pre><code>java -XX:+PrintFlagsFinal &gt; java-flags.md\n</code></pre> <p>Find specific flags by using grep on the output with a name</p> <pre><code>java -XX:+PrintFlagsFinal -version | grep MaxHeap\n</code></pre> Type Name Units ? ? uintx MaxHeapFreeRatio 70 {manageable} {default} size_t MaxHeapSize 8342470656 {product} {ergonomic} size_t SoftMaxHeapSize 8342470656 {manageable} {ergonomic}"},{"location":"reference/jvm/java-17-flags/#full-list-of-jvm-flags","title":"Full list of JVM flags","text":"Type Option Name Default value Product Category int ActiveProcessorCount -1 {product} {default} uintx AdaptiveSizeDecrementScaleFactor 4 {product} {default} uintx AdaptiveSizeMajorGCDecayTimeScale 10 {product} {default} uintx AdaptiveSizePolicyCollectionCostMargin 50 {product} {default} uintx AdaptiveSizePolicyInitializingSteps 20 {product} {default} uintx AdaptiveSizePolicyOutputInterval 0 {product} {default} uintx AdaptiveSizePolicyWeight 10 {product} {default} uintx AdaptiveSizeThroughPutPolicy 0 {product} {default} uintx AdaptiveTimeWeight 25 {product} {default} bool AdjustStackSizeForTLS false {product} {default} bool AggressiveHeap false {product} {default} intx AliasLevel 3 {C2 product} {default} bool AlignVector false {C2 product} {default} ccstr AllocateHeapAt {product} {default} intx AllocateInstancePrefetchLines 1 {product} {default} intx AllocatePrefetchDistance 256 {product} {default} intx AllocatePrefetchInstr 0 {product} {default} intx AllocatePrefetchLines 3 {product} {default} intx AllocatePrefetchStepSize 64 {product} {default} intx AllocatePrefetchStyle 1 {product} {default} bool AllowParallelDefineClass false {product} {default} bool AllowRedefinitionToAddDeleteMethods false {product} {default} bool AllowUserSignalHandlers false {product} {default} bool AllowVectorizeOnDemand true {C2 product} {default} bool AlwaysActAsServerClassMachine false {product} {default} bool AlwaysCompileLoopMethods false {product} {default} bool AlwaysLockClassLoader false {product} {default} bool AlwaysPreTouch false {product} {default} bool AlwaysRestoreFPU false {product} {default} bool AlwaysTenure false {product} {default} ccstr ArchiveClassesAtExit {product} {default} intx ArrayCopyLoadStoreMaxElem 8 {C2 product} {default} size_t AsyncLogBufferSize 2097152 {product} {default} intx AutoBoxCacheMax 128 {C2 product} {default} intx BCEATraceLevel 0 {product} {default} bool BackgroundCompilation true {pd product} {default} size_t BaseFootPrintEstimate 268435456 {product} {default} intx BiasedLockingBulkRebiasThreshold 20 {product} {default} intx BiasedLockingBulkRevokeThreshold 40 {product} {default} intx BiasedLockingDecayTime 25000 {product} {default} intx BiasedLockingStartupDelay 0 {product} {default} bool BlockLayoutByFrequency true {C2 product} {default} intx BlockLayoutMinDiamondPercentage 20 {C2 product} {default} bool BlockLayoutRotateLoops true {C2 product} {default} intx C1InlineStackLimit 5 {C1 product} {default} intx C1MaxInlineLevel 9 {C1 product} {default} intx C1MaxInlineSize 35 {C1 product} {default} intx C1MaxRecursiveInlineLevel 1 {C1 product} {default} intx C1MaxTrivialSize 6 {C1 product} {default} bool C1OptimizeVirtualCallProfiling true {C1 product} {default} bool C1ProfileBranches true {C1 product} {default} bool C1ProfileCalls true {C1 product} {default} bool C1ProfileCheckcasts true {C1 product} {default} bool C1ProfileInlinedCalls true {C1 product} {default} bool C1ProfileVirtualCalls true {C1 product} {default} bool C1UpdateMethodData true {C1 product} {default} intx CICompilerCount 12 {product} {ergonomic} bool CICompilerCountPerCPU true {product} {default} bool CITime false {product} {default} bool CheckJNICalls false {product} {default} bool ClassUnloading true {product} {default} bool ClassUnloadingWithConcurrentMark true {product} {default} bool ClipInlining true {product} {default} uintx CodeCacheExpansionSize 65536 {pd product} {default} bool CompactStrings true {pd product} {default} ccstr CompilationMode default {product} {default} ccstrlist CompileCommand {product} {default} ccstr CompileCommandFile {product} {default} ccstrlist CompileOnly {product} {default} intx CompileThreshold 10000 {pd product} {default} double CompileThresholdScaling 1.000000 {product} {default} intx CompilerThreadPriority -1 {product} {default} intx CompilerThreadStackSize 1024 {pd product} {default} size_t CompressedClassSpaceSize 1073741824 {product} {default} uint ConcGCThreads 3 {product} {ergonomic} intx ConditionalMoveLimit 3 {C2 pd product} {default} intx ContendedPaddingWidth 128 {product} {default} bool CrashOnOutOfMemoryError false {product} {default} bool CreateCoredumpOnCrash true {product} {default} bool CriticalJNINatives false {product} {default} bool DTraceAllocProbes false {product} {default} bool DTraceMethodProbes false {product} {default} bool DTraceMonitorProbes false {product} {default} bool DisableAttachMechanism false {product} {default} bool DisableExplicitGC false {product} {default} bool DisplayVMOutputToStderr false {product} {default} bool DisplayVMOutputToStdout false {product} {default} bool DoEscapeAnalysis true {C2 product} {default} bool DoReserveCopyInSuperWord true {C2 product} {default} bool DontCompileHugeMethods true {product} {default} bool DontYieldALot false {pd product} {default} ccstr DumpLoadedClassList {product} {default} bool DumpReplayDataOnError true {product} {default} bool DumpSharedSpaces false {product} {default} bool DynamicDumpSharedSpaces false {product} {default} bool EagerXrunInit false {product} {default} intx EliminateAllocationArraySizeLimit 64 {C2 product} {default} bool EliminateAllocations true {C2 product} {default} bool EliminateAutoBox true {C2 product} {default} bool EliminateLocks true {C2 product} {default} bool EliminateNestedLocks true {C2 product} {default} bool EnableContended true {product} {default} bool EnableDynamicAgentLoading true {product} {default} size_t ErgoHeapSizeLimit 0 {product} {default} ccstr ErrorFile {product} {default} bool ErrorFileToStderr false {product} {default} bool ErrorFileToStdout false {product} {default} uint64_t ErrorLogTimeout 120 {product} {default} double EscapeAnalysisTimeout 20.000000 {C2 product} {default} bool EstimateArgEscape true {product} {default} bool ExecutingUnitTests false {product} {default} bool ExitOnOutOfMemoryError false {product} {default} bool ExplicitGCInvokesConcurrent false {product} {default} bool ExtendedDTraceProbes false {product} {default} bool ExtensiveErrorReports false {product} {default} ccstr ExtraSharedClassListFile {product} {default} bool FilterSpuriousWakeups true {product} {default} bool FlightRecorder false {product} {default} ccstr FlightRecorderOptions {product} {default} bool ForceTimeHighResolution false {product} {default} intx FreqInlineSize 325 {C2 pd product} {default} double G1ConcMarkStepDurationMillis 10.000000 {product} {default} uintx G1ConcRSHotCardLimit 4 {product} {default} size_t G1ConcRSLogCacheSize 10 {product} {default} size_t G1ConcRefinementGreenZone 0 {product} {default} size_t G1ConcRefinementRedZone 0 {product} {default} uintx G1ConcRefinementServiceIntervalMillis 300 {product} {default} uint G1ConcRefinementThreads 13 {product} {ergonomic} size_t G1ConcRefinementThresholdStep 2 {product} {default} size_t G1ConcRefinementYellowZone 0 {product} {default} uintx G1ConfidencePercent 50 {product} {default} size_t G1HeapRegionSize 4194304 {product} {ergonomic} uintx G1HeapWastePercent 5 {product} {default} uintx G1MixedGCCountTarget 8 {product} {default} uintx G1PeriodicGCInterval 0 {manageable} {default} bool G1PeriodicGCInvokesConcurrent true {product} {default} double G1PeriodicGCSystemLoadThreshold 0.000000 {manageable} {default} intx G1RSetRegionEntries 768 {product} {default} intx G1RSetSparseRegionEntries 32 {product} {default} intx G1RSetUpdatingPauseTimePercent 10 {product} {default} uint G1RefProcDrainInterval 1000 {product} {default} uintx G1ReservePercent 10 {product} {default} uintx G1SATBBufferEnqueueingThresholdPercent 60 {product} {default} size_t G1SATBBufferSize 1024 {product} {default} size_t G1UpdateBufferSize 256 {product} {default} bool G1UseAdaptiveConcRefinement true {product} {default} bool G1UseAdaptiveIHOP true {product} {default} uintx GCDrainStackTargetSize 64 {product} {ergonomic} uintx GCHeapFreeLimit 2 {product} {default} uintx GCLockerEdenExpansionPercent 5 {product} {default} uintx GCPauseIntervalMillis 201 {product} {default} uintx GCTimeLimit 98 {product} {default} uintx GCTimeRatio 12 {product} {default} size_t HeapBaseMinAddress 2147483648 {pd product} {default} bool HeapDumpAfterFullGC false {manageable} {default} bool HeapDumpBeforeFullGC false {manageable} {default} intx HeapDumpGzipLevel 0 {manageable} {default} bool HeapDumpOnOutOfMemoryError false {manageable} {default} ccstr HeapDumpPath {manageable} {default} uintx HeapFirstMaximumCompactionCount 3 {product} {default} uintx HeapMaximumCompactionInterval 20 {product} {default} uintx HeapSearchSteps 3 {product} {default} size_t HeapSizePerGCThread 43620760 {product} {default} bool IgnoreEmptyClassPaths false {product} {default} bool IgnoreUnrecognizedVMOptions false {product} {default} uintx IncreaseFirstTierCompileThresholdAt 50 {product} {default} bool IncrementalInline true {C2 product} {default} uintx InitialCodeCacheSize 2555904 {pd product} {default} size_t InitialHeapSize 490733568 {product} {ergonomic} uintx InitialRAMFraction 64 {product} {default} double InitialRAMPercentage 1.562500 {product} {default} uintx InitialSurvivorRatio 8 {product} {default} uintx InitialTenuringThreshold 7 {product} {default} uintx InitiatingHeapOccupancyPercent 45 {product} {default} bool Inline true {product} {default} ccstr InlineDataFile {product} {default} intx InlineSmallCode 2500 {C2 pd product} {default} bool InlineSynchronizedMethods true {C1 product} {default} intx InteriorEntryAlignment 16 {C2 pd product} {default} intx InterpreterProfilePercentage 33 {product} {default} bool JavaMonitorsInStackTrace true {product} {default} intx JavaPriority10_To_OSPriority -1 {product} {default} intx JavaPriority1_To_OSPriority -1 {product} {default} intx JavaPriority2_To_OSPriority -1 {product} {default} intx JavaPriority3_To_OSPriority -1 {product} {default} intx JavaPriority4_To_OSPriority -1 {product} {default} intx JavaPriority5_To_OSPriority -1 {product} {default} intx JavaPriority6_To_OSPriority -1 {product} {default} intx JavaPriority7_To_OSPriority -1 {product} {default} intx JavaPriority8_To_OSPriority -1 {product} {default} intx JavaPriority9_To_OSPriority -1 {product} {default} size_t LargePageHeapSizeThreshold 134217728 {product} {default} size_t LargePageSizeInBytes 0 {product} {default} intx LiveNodeCountInliningCutoff 40000 {C2 product} {default} bool LoadExecStackDllInVMThread true {product} {default} intx LoopMaxUnroll 16 {C2 product} {default} intx LoopOptsCount 43 {C2 product} {default} intx LoopPercentProfileLimit 30 {C2 pd product} {default} uintx LoopStripMiningIter 1000 {C2 product} {default} uintx LoopStripMiningIterShortLoop 100 {C2 product} {default} intx LoopUnrollLimit 60 {C2 pd product} {default} intx LoopUnrollMin 4 {C2 product} {default} bool LoopUnswitching true {C2 product} {default} bool ManagementServer false {product} {default} size_t MarkStackSize 4194304 {product} {ergonomic} size_t MarkStackSizeMax 536870912 {product} {default} uint MarkSweepAlwaysCompactCount 4 {product} {default} uintx MarkSweepDeadRatio 5 {product} {default} intx MaxBCEAEstimateLevel 5 {product} {default} intx MaxBCEAEstimateSize 150 {product} {default} uint64_t MaxDirectMemorySize 0 {product} {default} bool MaxFDLimit true {product} {default} uintx MaxGCMinorPauseMillis 18446744073709551615 {product} {default} uintx MaxGCPauseMillis 200 {product} {default} uintx MaxHeapFreeRatio 70 {manageable} {default} size_t MaxHeapSize 7818182656 {product} {ergonomic} intx MaxInlineLevel 15 {C2 product} {default} intx MaxInlineSize 35 {C2 product} {default} intx MaxJNILocalCapacity 65536 {product} {default} intx MaxJavaStackTraceDepth 1024 {product} {default} intx MaxJumpTableSize 65000 {C2 product} {default} intx MaxJumpTableSparseness 5 {C2 product} {default} intx MaxLabelRootDepth 1100 {C2 product} {default} intx MaxLoopPad 15 {C2 product} {default} size_t MaxMetaspaceExpansion 5439488 {product} {default} uintx MaxMetaspaceFreeRatio 70 {product} {default} size_t MaxMetaspaceSize 18446744073709551615 {product} {default} size_t MaxNewSize 4689231872 {product} {ergonomic} intx MaxNodeLimit 80000 {C2 product} {default} uint64_t MaxRAM 137438953472 {pd product} {default} uintx MaxRAMFraction 4 {product} {default} double MaxRAMPercentage 25.000000 {product} {default} intx MaxRecursiveInlineLevel 1 {C2 product} {default} uintx MaxTenuringThreshold 15 {product} {default} intx MaxTrivialSize 6 {C2 product} {default} intx MaxVectorSize 32 {C2 product} {default} ccstr MetaspaceReclaimPolicy balanced {product} {default} size_t MetaspaceSize 22020096 {product} {default} bool MethodFlushing true {product} {default} size_t MinHeapDeltaBytes 4194304 {product} {ergonomic} uintx MinHeapFreeRatio 40 {manageable} {default} size_t MinHeapSize 8388608 {product} {ergonomic} intx MinInliningThreshold 250 {product} {default} intx MinJumpTableSize 10 {C2 pd product} {default} size_t MinMetaspaceExpansion 327680 {product} {default} uintx MinMetaspaceFreeRatio 40 {product} {default} uintx MinRAMFraction 2 {product} {default} double MinRAMPercentage 50.000000 {product} {default} uintx MinSurvivorRatio 3 {product} {default} size_t MinTLABSize 2048 {product} {default} intx MultiArrayExpandLimit 6 {C2 product} {default} uintx NUMAChunkResizeWeight 20 {product} {default} size_t NUMAInterleaveGranularity 2097152 {product} {default} uintx NUMAPageScanRate 256 {product} {default} size_t NUMASpaceResizeRate 1073741824 {product} {default} bool NUMAStats false {product} {default} ccstr NativeMemoryTracking off {product} {default} bool NeverActAsServerClassMachine false {pd product} {default} bool NeverTenure false {product} {default} uintx NewRatio 2 {product} {default} size_t NewSize 1363144 {product} {default} size_t NewSizeThreadIncrease 5320 {pd product} {default} intx NmethodSweepActivity 10 {product} {default} intx NodeLimitFudgeFactor 2000 {C2 product} {default} uintx NonNMethodCodeHeapSize 7602480 {pd product} {ergonomic} uintx NonProfiledCodeHeapSize 122027880 {pd product} {ergonomic} intx NumberOfLoopInstrToAlign 4 {C2 product} {default} intx ObjectAlignmentInBytes 8 {product lp64_product} {default} size_t OldPLABSize 1024 {product} {default} size_t OldSize 5452592 {product} {default} bool OmitStackTraceInFastThrow true {product} {default} ccstrlist OnError {product} {default} ccstrlist OnOutOfMemoryError {product} {default} intx OnStackReplacePercentage 140 {pd product} {default} bool OptimizeFill false {C2 product} {default} bool OptimizePtrCompare true {C2 product} {default} bool OptimizeStringConcat true {C2 product} {default} bool OptoBundling false {C2 pd product} {default} intx OptoLoopAlignment 16 {pd product} {default} bool OptoRegScheduling true {C2 pd product} {default} bool OptoScheduling false {C2 pd product} {default} uintx PLABWeight 75 {product} {default} bool PSChunkLargeArrays true {product} {default} int ParGCArrayScanChunk 50 {product} {default} uintx ParallelGCBufferWastePct 10 {product} {default} uint ParallelGCThreads 13 {product} {default} size_t ParallelOldDeadWoodLimiterMean 50 {product} {default} size_t ParallelOldDeadWoodLimiterStdDev 80 {product} {default} bool ParallelRefProcBalancingEnabled true {product} {default} bool ParallelRefProcEnabled true {product} {default} bool PartialPeelAtUnsignedTests true {C2 product} {default} bool PartialPeelLoop true {C2 product} {default} intx PartialPeelNewPhiDelta 0 {C2 product} {default} uintx PausePadding 1 {product} {default} intx PerBytecodeRecompilationCutoff 200 {product} {default} intx PerBytecodeTrapLimit 4 {product} {default} intx PerMethodRecompilationCutoff 400 {product} {default} intx PerMethodTrapLimit 100 {product} {default} bool PerfAllowAtExitRegistration false {product} {default} bool PerfBypassFileSystemCheck false {product} {default} intx PerfDataMemorySize 32768 {product} {default} intx PerfDataSamplingInterval 50 {product} {default} ccstr PerfDataSaveFile {product} {default} bool PerfDataSaveToFile false {product} {default} bool PerfDisableSharedMem false {product} {default} intx PerfMaxStringConstLength 1024 {product} {default} size_t PreTouchParallelChunkSize 4194304 {pd product} {default} bool PreferContainerQuotaForCPUCount true {product} {default} bool PreferInterpreterNativeStubs false {pd product} {default} intx PrefetchCopyIntervalInBytes 576 {product} {default} intx PrefetchFieldsAhead 1 {product} {default} intx PrefetchScanIntervalInBytes 576 {product} {default} bool PreserveAllAnnotations false {product} {default} bool PreserveFramePointer false {pd product} {default} size_t PretenureSizeThreshold 0 {product} {default} bool PrintClassHistogram false {manageable} {default} bool PrintCodeCache false {product} {default} bool PrintCodeCacheOnCompilation false {product} {default} bool PrintCommandLineFlags false {product} {default} bool PrintCompilation false {product} {default} bool PrintConcurrentLocks false {manageable} {default} bool PrintExtendedThreadInfo false {product} {default} bool PrintFlagsFinal true {product} {command line} bool PrintFlagsInitial false {product} {default} bool PrintFlagsRanges false {product} {default} bool PrintGC false {product} {default} bool PrintGCDetails false {product} {default} bool PrintHeapAtSIGBREAK true {product} {default} bool PrintSharedArchiveAndExit false {product} {default} bool PrintSharedDictionary false {product} {default} bool PrintStringTableStatistics false {product} {default} bool PrintTieredEvents false {product} {default} bool PrintVMOptions false {product} {default} bool PrintWarnings true {product} {default} uintx ProcessDistributionStride 4 {product} {default} bool ProfileInterpreter true {pd product} {default} intx ProfileMaturityPercentage 20 {product} {default} uintx ProfiledCodeHeapSize 122027880 {pd product} {ergonomic} uintx PromotedPadding 3 {product} {default} uintx QueuedAllocationWarningCount 0 {product} {default} int RTMRetryCount 5 {ARCH product} {default} bool RangeCheckElimination true {product} {default} bool ReassociateInvariants true {C2 product} {default} bool RecordDynamicDumpInfo false {product} {default} bool ReduceBulkZeroing true {C2 product} {default} bool ReduceFieldZeroing true {C2 product} {default} bool ReduceInitialCardMarks true {C2 product} {default} bool ReduceSignalUsage false {product} {default} intx RefDiscoveryPolicy 0 {product} {default} bool RegisterFinalizersAtInit true {product} {default} bool RelaxAccessControlCheck false {product} {default} ccstr ReplayDataFile {product} {default} bool RequireSharedSpaces false {product} {default} uintx ReservedCodeCacheSize 251658240 {pd product} {ergonomic} bool ResizePLAB true {product} {default} bool ResizeTLAB true {product} {default} bool RestoreMXCSROnJNICalls false {product} {default} bool RestrictContended true {product} {default} bool RestrictReservedStack true {product} {default} bool RewriteBytecodes true {pd product} {default} bool RewriteFrequentPairs true {pd product} {default} bool SafepointTimeout false {product} {default} intx SafepointTimeoutDelay 10000 {product} {default} bool ScavengeBeforeFullGC false {product} {default} bool SegmentedCodeCache true {product} {ergonomic} intx SelfDestructTimer 0 {product} {default} ccstr SharedArchiveConfigFile {product} {default} ccstr SharedArchiveFile {product} {default} size_t SharedBaseAddress 34359738368 {product} {default} ccstr SharedClassListFile {product} {default} uintx SharedSymbolTableBucketSize 4 {product} {default} ccstr ShenandoahGCHeuristics adaptive {product} {default} ccstr ShenandoahGCMode satb {product} {default} bool ShowCodeDetailsInExceptionMessages true {manageable} {default} bool ShowMessageBoxOnError false {product} {default} bool ShrinkHeapInSteps true {product} {default} size_t SoftMaxHeapSize 7818182656 {manageable} {ergonomic} intx SoftRefLRUPolicyMSPerMB 1000 {product} {default} bool SplitIfBlocks true {C2 product} {default} intx StackRedPages 1 {pd product} {default} intx StackReservedPages 1 {pd product} {default} intx StackShadowPages 20 {pd product} {default} bool StackTraceInThrowable true {product} {default} intx StackYellowPages 2 {pd product} {default} uintx StartAggressiveSweepingAt 10 {product} {default} bool StartAttachListener false {product} {default} ccstr StartFlightRecording {product} {default} uint StringDeduplicationAgeThreshold 3 {product} {default} uintx StringTableSize 65536 {product} {default} bool SuperWordLoopUnrollAnalysis true {C2 pd product} {default} bool SuperWordReductions true {C2 product} {default} bool SuppressFatalErrorMessage false {product} {default} uintx SurvivorPadding 3 {product} {default} uintx SurvivorRatio 8 {product} {default} double SweeperThreshold 0.500000 {product} {default} uintx TLABAllocationWeight 35 {product} {default} uintx TLABRefillWasteFraction 64 {product} {default} size_t TLABSize 0 {product} {default} bool TLABStats true {product} {default} uintx TLABWasteIncrement 4 {product} {default} uintx TLABWasteTargetPercent 1 {product} {default} uintx TargetPLABWastePct 10 {product} {default} uintx TargetSurvivorRatio 50 {product} {default} uintx TenuredGenerationSizeIncrement 20 {product} {default} uintx TenuredGenerationSizeSupplement 80 {product} {default} uintx TenuredGenerationSizeSupplementDecay 2 {product} {default} intx ThreadPriorityPolicy 0 {product} {default} bool ThreadPriorityVerbose false {product} {default} intx ThreadStackSize 1024 {pd product} {default} uintx ThresholdTolerance 10 {product} {default} intx Tier0BackedgeNotifyFreqLog 10 {product} {default} intx Tier0InvokeNotifyFreqLog 7 {product} {default} intx Tier0ProfilingStartPercentage 200 {product} {default} intx Tier23InlineeNotifyFreqLog 20 {product} {default} intx Tier2BackEdgeThreshold 0 {product} {default} intx Tier2BackedgeNotifyFreqLog 14 {product} {default} intx Tier2CompileThreshold 0 {product} {default} intx Tier2InvokeNotifyFreqLog 11 {product} {default} intx Tier3BackEdgeThreshold 60000 {product} {default} intx Tier3BackedgeNotifyFreqLog 13 {product} {default} intx Tier3CompileThreshold 2000 {product} {default} intx Tier3DelayOff 2 {product} {default} intx Tier3DelayOn 5 {product} {default} intx Tier3InvocationThreshold 200 {product} {default} intx Tier3InvokeNotifyFreqLog 10 {product} {default} intx Tier3LoadFeedback 5 {product} {default} intx Tier3MinInvocationThreshold 100 {product} {default} intx Tier4BackEdgeThreshold 40000 {product} {default} intx Tier4CompileThreshold 15000 {product} {default} intx Tier4InvocationThreshold 5000 {product} {default} intx Tier4LoadFeedback 3 {product} {default} intx Tier4MinInvocationThreshold 600 {product} {default} bool TieredCompilation true {pd product} {default} intx TieredCompileTaskTimeout 50 {product} {default} intx TieredRateUpdateMaxTime 25 {product} {default} intx TieredRateUpdateMinTime 1 {product} {default} intx TieredStopAtLevel 4 {product} {default} bool TimeLinearScan false {C1 product} {default} ccstr TraceJVMTI {product} {default} intx TrackedInitializationLimit 50 {C2 product} {default} bool TrapBasedNullChecks false {pd product} {default} bool TrapBasedRangeChecks false {C2 pd product} {default} intx TypeProfileArgsLimit 2 {product} {default} uintx TypeProfileLevel 111 {pd product} {default} intx TypeProfileMajorReceiverPercent 90 {C2 product} {default} intx TypeProfileParmsLimit 2 {product} {default} intx TypeProfileWidth 2 {product} {default} intx UnguardOnExecutionViolation 0 {product} {default} bool UseAES true {product} {default} intx UseAVX 2 {ARCH product} {default} bool UseAdaptiveGenerationSizePolicyAtMajorCollection true {product} {default} bool UseAdaptiveGenerationSizePolicyAtMinorCollection true {product} {default} bool UseAdaptiveNUMAChunkSizing true {product} {default} bool UseAdaptiveSizeDecayMajorGCCost true {product} {default} bool UseAdaptiveSizePolicy true {product} {default} bool UseAdaptiveSizePolicyFootprintGoal true {product} {default} bool UseAdaptiveSizePolicyWithSystemGC false {product} {default} bool UseAddressNop true {ARCH product} {default} bool UseBASE64Intrinsics false {product} {default} bool UseBMI1Instructions true {ARCH product} {default} bool UseBMI2Instructions true {ARCH product} {default} bool UseBiasedLocking false {product} {default} bool UseBimorphicInlining true {C2 product} {default} bool UseCLMUL true {ARCH product} {default} bool UseCMoveUnconditionally false {C2 product} {default} bool UseCodeAging true {product} {default} bool UseCodeCacheFlushing true {product} {default} bool UseCompiler true {product} {default} bool UseCompressedClassPointers true {product lp64_product} {ergonomic} bool UseCompressedOops true {product lp64_product} {ergonomic} bool UseCondCardMark false {product} {default} bool UseContainerSupport true {product} {default} bool UseCountLeadingZerosInstruction true {ARCH product} {default} bool UseCountTrailingZerosInstruction true {ARCH product} {default} bool UseCountedLoopSafepoints true {C2 product} {default} bool UseCounterDecay true {product} {default} bool UseDivMod true {C2 product} {default} bool UseDynamicNumberOfCompilerThreads true {product} {default} bool UseDynamicNumberOfGCThreads true {product} {default} bool UseEmptySlotsInSupers true {product} {default} bool UseFMA true {product} {default} bool UseFPUForSpilling true {C2 product} {default} bool UseFastJNIAccessors true {product} {default} bool UseFastStosb false {ARCH product} {default} bool UseG1GC true {product} {ergonomic} bool UseGCOverheadLimit true {product} {default} bool UseHeavyMonitors false {product} {default} bool UseHugeTLBFS false {product} {default} bool UseInlineCaches true {product} {default} bool UseInterpreter true {product} {default} bool UseJumpTables true {C2 product} {default} bool UseLargePages false {pd product} {default} bool UseLargePagesIndividualAllocation false {pd product} {default} bool UseLinuxPosixThreadCPUClocks true {product} {default} bool UseLoopCounter true {product} {default} bool UseLoopInvariantCodeMotion true {C1 product} {default} bool UseLoopPredicate true {C2 product} {default} bool UseMaximumCompactionOnSystemGC true {product} {default} bool UseNUMA false {product} {default} bool UseNUMAInterleaving false {product} {default} bool UseNewLongLShift true {ARCH product} {default} bool UseNotificationThread true {product} {default} bool UseOnStackReplacement true {pd product} {default} bool UseOnlyInlinedBimorphic true {C2 product} {default} bool UseOprofile false {product} {default} bool UseOptoBiasInlining false {C2 product} {default} bool UsePSAdaptiveSurvivorSizePolicy true {product} {default} bool UseParallelGC false {product} {default} bool UsePerfData true {product} {default} bool UsePopCountInstruction true {product} {default} bool UseProfiledLoopPredicate true {C2 product} {default} bool UseRTMDeopt false {ARCH product} {default} bool UseRTMLocking false {ARCH product} {default} bool UseSHA true {product} {default} bool UseSHM false {product} {default} intx UseSSE 4 {ARCH product} {default} bool UseSSE42Intrinsics true {ARCH product} {default} bool UseSerialGC false {product} {default} bool UseSharedSpaces true {product} {default} bool UseShenandoahGC false {product} {default} bool UseSignalChaining true {product} {default} bool UseStoreImmI16 true {ARCH product} {default} bool UseStringDeduplication false {product} {default} bool UseSubwordForMaxVector true {C2 product} {default} bool UseSuperWord true {C2 product} {default} bool UseTLAB true {product} {default} bool UseThreadPriorities true {pd product} {default} bool UseTransparentHugePages false {product} {default} bool UseTypeProfile true {product} {default} bool UseTypeSpeculation true {C2 product} {default} bool UseUnalignedLoadStores true {ARCH product} {default} bool UseVectorCmov false {C2 product} {default} bool UseXMMForArrayCopy true {product} {default} bool UseXMMForObjInit true {ARCH product} {default} bool UseXmmI2D true {ARCH product} {default} bool UseXmmI2F true {ARCH product} {default} bool UseXmmLoadAndClearUpper true {ARCH product} {default} bool UseXmmRegToRegMoveAll true {ARCH product} {default} bool UseZGC false {product} {default} intx VMThreadPriority -1 {product} {default} intx VMThreadStackSize 1024 {pd product} {default} intx ValueMapInitialSize 11 {C1 product} {default} intx ValueMapMaxLoopSize 8 {C1 product} {default} intx ValueSearchLimit 1000 {C2 product} {default} bool VerifySharedSpaces false {product} {default} uintx YoungGenerationSizeIncrement 20 {product} {default} uintx YoungGenerationSizeSupplement 80 {product} {default} uintx YoungGenerationSizeSupplementDecay 8 {product} {default} size_t YoungPLABSize 4096 {product} {default} double ZAllocationSpikeTolerance 2.000000 {product} {default} double ZCollectionInterval 0.000000 {product} {default} double ZFragmentationLimit 25.000000 {product} {default} size_t ZMarkStackSpaceLimit 8589934592 {product} {default} bool ZProactive true {product} {default} bool ZUncommit true {product} {default} uintx ZUncommitDelay 300 {product} {default} bool ZeroTLAB false {product} {default}"},{"location":"reference/jvm/profile-tools/","title":"Profile JVM applications","text":"<p>Profile applications on the JVM, visualising memory and CPU resources, identifying bottlenecks and areas of the code to review to optimise a running application.</p> <p> Using FlameGraphs To Illuminate The JVM  A Simple Approach to the Advanced JVM Profiling</p>"},{"location":"reference/jvm/profile-tools/#visualvm","title":"VisualVM","text":"<p>VisualVM provides a simplified and robust profiling tool for Java applications, bundled with the Java Development Kit (JDK) and using JConsole, jstat, jstack, jinfo, and jmap.</p> <p></p> UbuntuMacOSX <p>Ubuntu / Debian includes VisualVM in the software center <pre><code>sudo apt install visualvm\n</code></pre></p> <p>Download the macOS application bundle and double-click to install.</p>"},{"location":"reference/jvm/profile-tools/#jdk-flight-recorder","title":"JDK Flight Recorder","text":"<p>JDK Flight Recorder is a production time profiling and diagnostics engine built into the JVM</p> <ul> <li>Extremely low overhead - no measurable impact on the running application</li> <li>High performance flight recording engine and high performance data collection</li> <li>Safe and reliable in production, tested on all platforms as part of the JVM/JDK-testing</li> <li>Time machine records data before, up to, and right after a problem occurs (even if the JVM process crashes)</li> </ul> <p><code>jcmd</code> to access the flight recorder data from the command line</p> <p>Mission control provides a graphical tool to visualise flight recorder data.</p> <ul> <li> Continuous Monitoring with JDK Flight Recorder</li> <li> JDK11 - Introduction to JDK Flight Recorder</li> <li> Production profiling with JDK Flight Recorder &amp; JDK Mission Control</li> </ul>"},{"location":"reference/jvm/profile-tools/#mission-control","title":"Mission Control","text":"<p>Mission Control is an open source desktop tool for visualising production time profiling and diagnostics from the JDK flight recorder tool. JDK Mission Control supports OpenJDK 11 and above.</p> <p>JDK Mission Control consists of</p> <ul> <li>A JDK Flight Recorder (JFR) analyser and visualiser</li> <li>A Java Management Extensions (JMX) Console</li> <li>A heap dump (hprof format) analyzer (JOverflow)</li> </ul> <p>Eclipse Mission Control from Adoptium</p> <p>Java Mission Control demo - 2014 outated but might be useful if nothing newer</p> <p> </p>"},{"location":"reference/jvm/profile-tools/#profiling-guides","title":"Profiling guides","text":"<p>Profiling your Java Application - A Beginner\u2019s Guide - Victor Rentea</p> <p>Explore three of the best free tools for profiling a Java (Spring) application:</p> <ul> <li>Using Java Flight Recorder to profile method execution times</li> <li>Using Micrometer-Prometheus-Grafana to profile connection starvation issues</li> <li>Using Glowroot to identify long-running queries</li> </ul> <p> </p>"},{"location":"reference/jvm/profile-tools/#references","title":"References","text":"<p>Java Profilers - Baeldung HotSpot Virtual Machine Garbage Collection Tuning Guide - Oracle</p>"},{"location":"reference/jvm/understanding-memory-usage/","title":"Memory usage","text":"<p>Adjusting the heap size and Garbage Collection behaviour is often the simplest means to improving application performance and stability. A mismatch between the heap size.</p> <p>Allocating additional memory to the HotSpot JVM is a relatively cheap way to improve the performance of an application.</p> <p>Garbage collection cost is in the form of execution pauses while the HotSpot JVM cleans up the no-longer-needed heap allocations.</p> <p>Report a full breakdown of the HotSpot JVM\u2019s memory usage upon exit using the following option combination:</p> <p>JVM Memory Usage Report</p> <p>```shell -XX:+UnlockDiagnosticVMOptions \u2011XX:NativeMemoryTracking=summary \u2011XX:+PrintNMTStatistics.</p> <p>```</p>"},{"location":"reference/jvm/understanding-memory-usage/#out-of-memory-errors","title":"Out Of Memory errors","text":"<p>When experiencing <code>OutOfMemory</code> errors, consider how the HotSpot JVM should behave if the application runs out of memory.</p> <p><code>-XX:+ExitOnOutOfMemoryError</code> - HotSpot JVM exits on the first OutOfMemory error, suitable if the JVM will be automatically restarted (such as in container services)</p> <p><code>-XX:+HeapDumpOnOutOfMemoryError</code> - dump contents of heap to file, <code>&lt;java_pid&gt;.hprof</code>, to help diagnose memory leaks</p> <p><code>-XX:HeapDumpPath</code> defines the path for the heap dump, default is current directory</p>"},{"location":"reference/jvm/understanding-memory-usage/#choose-a-garbage-collector","title":"Choose A Garbage Collector","text":"<p>The HotSpot Virtual Machine Garbage Collection Tuning Guide provides advice on selecting a suitable garbage collector (GC)</p> <p>G1GC collector is the default used by the JDK ergonomics process on most hardware.</p> <p>Other garbage collectors available include:</p> <p><code>-XX:+UseSerialGC</code> - serial collector, performing all GC work on a single thread</p> <p><code>-XX:+UseParallelGC</code> - parallel (throughput) collector, performs compaction using multiple threads.</p> <p><code>-XX:+UseZGC</code> - ZGC collector scalable low latency garbage collector (experimental in JDK 11, so requires <code>-XX:+UnlockExperimentalVMOptions</code>).</p> <p>Enable garbage collection logging</p> <p><code>-Xlog:gc</code> - basic GC logging</p> <p><code>-Xlog:gc*</code> - verbose GC logging</p>"},{"location":"reference/jvm/understanding-memory-usage/#object-allocation","title":"Object Allocation","text":"<p>Applications that create short-lived objects at a high allocation rates can lead to the premature promotion of short-lived objects to the old-generation heap space. There the objects will accumulate until a full garbage collection is needed</p> <p>To avoid premature promotion:</p> <p><code>-XX:NewSize=n</code> - initial size for the young generation</p> <p><code>-XX:MaxNewSize=n</code> - maximum size for the young generation</p> <p><code>-XX:MaxTenuringThreshold=n</code> - maximum number of young-generation collections an object can survive before it is promoted to the old generation</p>"},{"location":"reference/jvm/understanding-memory-usage/#just-in-time-optimisation","title":"Just In Time Optimisation","text":"<p>Understand how the Just In Time (JIT) compiler optimises the code.</p> <p>Once an application garbage collection pauses are an acceptable level, check the JIT compilers are optimizing the parts of your program you think are important for performance.</p> <p>Enable compilation logging:</p> <p><code>-XX:+PrintCompilation</code> print basic information about each JIT compilation to the console</p> <p><code>-XX:+UnlockDiagnosticVMOptions \u2011XX:+PrintCompilation \u2011XX:+PrintInlining</code> - information about method in-lining</p>"},{"location":"reference/performance/","title":"Clojure Performance","text":"<p>Two excellent presentations on Clojure performance</p>"},{"location":"reference/performance/#optimising-the-critical-path","title":"Optimising the critical path","text":"<p>Using two of Clojure's fundamental building blocks, macros and higher order functions, Clojure code can be sped up significantly without sacrificing common idioms.</p> <p>Premature optimisation is the root of all evil, this is not a reason to pass up opportunities to improve the critical 3%.</p> <p> </p>"},{"location":"reference/performance/#naked-performance","title":"Naked Performance","text":"<p>Lessons learned on building Clojure/Script systems that are both ridiculously fast and will fail fast on errors.</p> <p>Compare the performance of mutable, persistent &amp; zero-copy data structures, showing how to use interpreters and compilers to build beautiful and performant abstractions.</p> <p>A shot demo on building a simple non-blocking web server that runs idiomatic Clojure to serve millions of requests per second.</p> <p> </p>"},{"location":"reference/performance/#advanced-types","title":"Advanced types","text":"<p>Clojure support for Java Primitives</p> <p>Clojure has support for high-performance with Java primitive types in local contexts. All Java primitive types are supported: int, float, long, double, boolean, char, short, and byte.  In the extremely rare occasions where this is needed, it is added via metadata and therefore only adds to the existing code without rewriting it.</p> <p>Rather than write this Java:</p> <pre><code>static public float asum(float[] xs){\n  float ret = 0;\n  for(int i = 0; i &lt; xs.length; i++)\n    ret += xs[i];\n  return ret;\n}\n</code></pre> <p>you can write this Clojure:</p> <pre><code>(defn asum [^floats xs]\n  (areduce xs i ret (float 0)\n    (+ ret (aget xs i))))\n</code></pre> <p>and the resulting code is exactly the same speed (when run with java -server).</p>"},{"location":"reference/performance/#optimization-tips-for-types","title":"Optimization tips for types","text":"<p>All arguments are passed to Clojure fns as objects, so there's no point to putting non-array primitive type hints on fn args. Instead, use the let technique shown to place args in primitive locals if they need to participate in primitive arithmetic in the body.    (let [foo (int bar)] ...) is the correct way to get a primitive local. Do not use ^Integer etc.</p> <p>Don't rush to unchecked math unless you want truncating operations. HotSpot does a good job at optimizing the overflow check, which will yield an exception instead of silent truncation. On a typical example, that has about a 5% difference in speed - well worth it. Also, people reading your code don't know if you are using unchecked for truncation or performance - best to reserve it for the former and comment if the latter.</p> <p>There's usually no point in trying to optimize an outer loop, in fact it can hurt you as you'll be representing things as primitives which just have to be re-boxed in order to become args to the inner call. The only exception is reflection warnings - you must get rid of them in any code that gets called frequently.</p> <p>Almost every time someone presents something they are trying to optimize with hints, the faster version has far fewer hints than the original. If a hint doesn't improve things in the end - take it out.</p> <p>Many people seem to presume only the unchecked- ops do primitive arithmetic - not so. When the args are primitive locals, regular + and * etc do primitive math with an overflow check - fast and safe.</p> <p>So, the simplest route to fast math is to leave the operators alone and just make sure the source literals and locals are primitive. Arithmetic on primitives yields primitives. If you've got a loop (which you probably do if you need to optimize) make sure the loop locals are primitives first - then if you accidentally are producing a boxed intermediate result you'll get an error on recur. Don't solve that error by coercing your intermediate result, instead, figure out what argument or local is not primitive.</p>"},{"location":"reference/standard-library/","title":"Clojure Standard Library","text":"<p>Examples of using the functions from the <code>clojure.core</code> namespace and other important functions, macros and special forms that are part of the <code>org.clojure/clojure</code> library.</p> <p>There are approximately 700 functions and macros available in the <code>clojure.core</code> namespace.  These are referred to as the Clojure Standard Library.</p> <p>Counting functions in <code>clojure.core</code></p> <p>To get an accurate number of functions, call the <code>ns-publics</code> function with a namespace name <pre><code>(count (ns-publics 'clojure.core))\n</code></pre> Random Function is a simple project that prints out a random function from the given namespace, or from clojure.core by default.</p>"},{"location":"reference/standard-library/#functions-macros-and-special-forms","title":"Functions, Macros and Special forms","text":"<p>The majority of times macros and special forms act just like any other defined function (i.e. <code>fn</code>, <code>defn</code>)</p> <p>A macro is a piece of code that evaluates into a function when read by the macro reader, or by the developer using <code>macroexpand</code> function.  An expanded macro may also contain macros, so expansion could take place several levels (<code>macroexpand-all</code>).</p> <p>macros are not composable like functions, so functions like <code>apply</code> <code>reduce</code> <code>map</code> cannot use a macro (use a function instead).</p> <p>Special forms are built into the Clojure runtime, so will not be found in clojure.core</p> <ul> <li>Special forms: <code>if</code> <code>do</code> <code>let</code> <code>quote</code> <code>var</code> <code>fn</code> <code>loop</code> <code>recur</code> <code>throw</code> <code>try</code></li> <li>Special forms for Java interop:  <code>.</code> <code>new</code> <code>set!</code></li> </ul>"},{"location":"reference/standard-library/collections/","title":"Standard Library: Collections","text":"<p>Functions to create and work with the Clojure collection types, mainly maps, vectors and sets</p> <p>See Sequences for functions around lists and (lazy) sequences</p>"},{"location":"reference/standard-library/cond-thread-macro/","title":"Clojure cond-&gt;","text":"<p><code>cond-&gt;</code> and <code>cond-&gt;&gt;</code> are versatile macros available since version 1.5, although its more of a nieche use, its really useful in that neiche</p> <p>Usage: (cond-&gt; expr &amp; clauses)</p> <p>Takes an expression and a set of test/form pairs.</p> <p>Threads expr (via -&gt;) through each form for which the corresponding test expression is true.</p> <p>Note that, unlike cond branching, cond-&gt; threading does not short circuit after the first true test expression.</p>"},{"location":"reference/standard-library/cond-thread-macro/#deconstruct","title":"Deconstruct","text":"<pre><code>(cond-&gt; 10\n  false inc)\n;; =&gt; 10\n</code></pre> <p>In the above example 10 is the expr mentioned in the docstring and everything after it are the clauses.</p> <p>Each clause is a pair made up of a test and a form.  There is a single clause with the value false as the test the function inc as the form.</p> <p>Since the test evaluates to a false value the expression is not threaded into the form. As a result the original expression, 10, is returned.</p> <p>Let\u2019s look at an example with a truthy test.</p> <pre><code>(cond-&gt; 10\n  true (- 2)\n;;=&gt; 8\n</code></pre> <p>Once again, 10 is the starting expression. The single clause has a test that evaluates to true so the expression is threaded into the first position of the form (- 2). The result is 8 and this is returned.</p> <p>An example of a <code>cond-&gt;</code> with multiple clauses. Explanations are inline with the code.</p> <pre><code>(cond-&gt; 10 ; start with 10\n  ;; test evaluates to true, so apply inc to 10. Current value is now 11.\n  true inc\n\n  ;; (zero? 1) evaluates to false, do not perform action. Current value stays 11.\n  (zero? 1) (+ 2)\n\n  ;; (pos? 4) evaluates to true, thread 11 into first position of form.\n  (pos? 4) (- 5))\n;; =&gt; 6 ; The result of (- 11 5) is 6.\n</code></pre> <p>If you understand the above example then you have a good grasp of cond-&gt;. But when is this functionality useful?</p>"},{"location":"reference/standard-library/cond-thread-macro/#when-to-use-cond-","title":"When to use cond-&gt;?","text":"<p>Looking through the codebases I work on, I almost primarily see cond-&gt; being used with the initial expression being a hash-map. It is being used in situations where we want to selectively assoc, update, or dissoc something from a map.</p> <p>If cond-&gt; did not exist you would accomplish those selective modifications with code similar to below.</p> <pre><code>(if (some-pred? q)\n  (assoc m :a-key :a-value)\n  m)\n</code></pre> <p>Rewrite the above with cond-&gt;.</p> <pre><code>(cond-&gt; m\n  (some-pred? q) (assoc :a-key :a-value))\n</code></pre> <p>If you\u2019re not used to seeing cond-&gt; the above transformation might seem like a step backwards. I know it felt that way to me when I first saw cond-&gt;. Give yourself time to get familiar with it and you\u2019ll be glad you\u2019re using it.</p> <p>A meatier example of using cond-&gt; is demonstrated below. Here we\u2019re manipulating data structures designed for use with honeysql to generate SQL statements. We start with a base-query and selectively modify it based on incoming parameters.</p> <pre><code>(defn query [req-params]\n  (let [and-clause (fnil conj [:and])\n        base-query {:select [:name :job]\n                    :from [:person]}]\n    (cond-&gt; base-query\n      (:job req-params) (update :where and-clause [:= :job (:job req-params)])\n      (:name req-params) (update :where and-clause [:= :name (:name req-params)])\n      (:min-age req-params) (update :where and-clause [:&gt; :age (:min-age req-params)]))))\n</code></pre> <p>Hopefully this gives you a taste of cond-&gt;. I\u2019ve found it to be quite useful. It has a place in every Clojure developer\u2019s toolbox.</p>"},{"location":"reference/standard-library/destructuring/","title":"Destructuring","text":"<p>Destructuring is a form of pattern matching where you return specific elements from a collection and assign those elements names.  It is commonly used in function parameter lists or with the <code>let</code> function.</p> <p>Destructuring is also known as abstract structural binding</p> <p>A simple example of destructuring is assigning the values of a collection, in this case a vector.</p> <pre><code>(def co-ordinates [5 7])\n\n(let [[x y] co-ordinates]\n (str \"x:\" x \"y:\" y))\n;; =&gt; x: 5 y: 7\n</code></pre> <p>;; Sometimes we do not need all the information, so we can just use the elements we need.</p> <pre><code>(def three-dee-co-ordinates [2 7 4])\n\n(let [[x y] three-dee-co-ordinates]\n  (str \"I only need the 2D co-ordinates, X: \" x \" and Y: \" y ))\n;; =&gt; \"I only need the 2D co-ordinates, X: 2 and Y: 7\"\n</code></pre> <p>Its quite common to take the first element as a specific name and use another name for the rest of the elements</p> <pre><code>(def shopping-list [\"oranges\" \"apples\" \"spinach\" \"carrots\" \"potatoes\" \"beetroot\"])\n\n(defn get-item [items]\n  (let [[next-item &amp; other-items] items]\n    (str \"The next item to get is: \" next-item)))\n\n(get-item shopping-list)\n;; =&gt; \"The next item to get is: oranges\"\n</code></pre> <p>This example seems a little redundant at first, however if we add recursion then we can iterate through the shopping list and it should make more sense</p> <p>splitting a vector into a head and a tail. When defining a function with an arglist** you use an ampersand. The same is true in destructuring.</p> <pre><code>(def indexes [1 2 3])\n\n(let [[x &amp; more] indexes]\n         (println \"x:\" x \"more:\" more))\n;; =&gt; x: 1 more: (2 3)\n</code></pre> <p>It's also worth noting that you can bind the entire vector to a local using the :as directive.</p> <pre><code>(def indexes [1 2 3])\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userindexes","title":"'user/indexes","text":"<pre><code> (let [[x &amp; more :as full-list] indexes]\n         (println \"x:\" x \"more:\" more \"full list:\" full-list))\n;; =&gt; x: 1 more: (2 3) full list: [1 2 3]\n</code></pre> <p>Vector examples are the easiest; however, in practice I find myself using destructuring with maps far more often.</p> <p>Simple destructuring on a map is as easy as choosing a local name and providing the key.</p> <pre><code>(def point {:x 5 :y 7})\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userpoint","title":"'user/point","text":"<pre><code> (let [{the-x :x the-y :y} point]\n         (println \"x:\" the-x \"y:\" the-y))\n;; =&gt; x: 5 y: 7\n</code></pre> <p>As the example shows, the values of :x and :y are bound to locals with the names the-x and the-y. In practice we would never prepend \"the-\" to our local names; however, using different names provides a bit of clarity for our first example. In production code you would be much more likely to want locals with the same name as the key. This works perfectly well, as the next example shows.</p> <pre><code>(def point {:x 5 :y 7})\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userpoint_1","title":"'user/point","text":"<p>user=&gt; (let [{x :x y :y} point]          (println \"x:\" x \"y:\" y)) x: 5 y: 7</p> <p>While this works perfectly well, creating locals with the same name as the keys becomes tedious and annoying (especially when your keys are longer than one letter). Clojure anticipates this frustration and provides :keys directive that allows you to specify keys that you would like as locals with the same name.</p> <p>user=&gt; (def point {:x 5 :y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_2","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y]} point]          (println \"x:\" x \"y:\" y)) x: 5 y: 7</p> <p>There are a few directives that work while destructuring maps. The above example shows the use of :keys. In practice I end up using :keys the most; however, I've also used the :as directive while working with maps.</p> <p>The following example illustrates the use of an :as directive to bind a local with the entire map.</p> <p>user=&gt; (def point {:x 5 :y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_3","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y] :as the-point} point]          (println \"x:\" x \"y:\" y \"point:\" the-point)) x: 5 y: 7 point: {:x 5, :y 7}</p> <p>We've now seen the :as directive used for both vectors and maps. In both cases the local is always assigned to the entire expression that is being destructured.</p> <p>For completeness I'll document the :or directive; however, I must admit that I've never used it in practice. The :or directive is used to assign default values when the map being destructured doesn't contain a specified key.</p> <p>user=&gt; (def point {:y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_4","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y] :or {x 0 y 0}} point]          (println \"x:\" x \"y:\" y)) x: 0 y: 7</p> <p>Lastly, it's also worth noting that you can destructure nested maps, vectors and a combination of both.</p> <p>The following example destructures a nested map</p> <p>user=&gt; (def book {:name \"SICP\" :details {:pages 657 :isbn-10 \"0262011530\"}})</p>"},{"location":"reference/standard-library/destructuring/#userbook","title":"'user/book","text":"<p>user=&gt; (let [{name :name {pages :pages isbn-10 :isbn-10} :details} book]          (println \"name:\" name \"pages:\" pages \"isbn-10:\" isbn-10)) name: SICP pages: 657 isbn-10: 0262011530</p> <p>As you would expect, you can also use directives while destructuring nested maps.</p> <p>user=&gt; (def book {:name \"SICP\" :details {:pages 657 :isbn-10 \"0262011530\"}})</p>"},{"location":"reference/standard-library/destructuring/#userbook_1","title":"'user/book","text":"<p>user=&gt; user=&gt; (let [{name :name {:keys [pages isbn-10]} :details} book]          (println \"name:\" name \"pages:\" pages \"isbn-10:\" isbn-10)) name: SICP pages: 657 isbn-10: 0262011530</p> <p>Destructuring nested vectors is also very straight-forward, as the following example illustrates</p> <p>user=&gt; (def numbers [[1 2][3 4]])</p>"},{"location":"reference/standard-library/destructuring/#usernumbers","title":"'user/numbers","text":"<p>user=&gt; (let [[[a b][c d]] numbers]   (println \"a:\" a \"b:\" b \"c:\" c \"d:\" d)) a: 1 b: 2 c: 3 d: 4</p> <pre><code>Since binding forms can be nested within one another arbitrarily, you can pull apart just about anything -- http://clojure.org/special_forms\n</code></pre> <p>The following example destructures a map and a vector at the same time.</p> <p>user=&gt; (def golfer {:name \"Jim\" :scores [3 5 4 5]})</p>"},{"location":"reference/standard-library/destructuring/#usergolfer","title":"'user/golfer","text":"<p>user=&gt; (let [{name :name [hole1 hole2] :scores} golfer]          (println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2)) name: Jim hole1: 3 hole2: 5</p> <p>The same example can be rewritten using a function definition to show the simplicity of using destructuring in parameter lists.</p> <p>user=&gt; (defn print-status [{name :name [hole1 hole2] :scores}]   (println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))</p>"},{"location":"reference/standard-library/destructuring/#userprint-status","title":"'user/print-status","text":"<p>user=&gt; (print-status {:name \"Jim\" :scores [3 5 4 5]}) name: Jim hole1: 3 hole2: 5</p> <p>There are other (less used) directives and deeper explanations available on http://clojure.org/special_forms and in The Joy of Clojure. I recommend both.</p> <p>**(defn do-something [x y &amp; more] ... ) Posted by Jay Fields at 7:44 AM Email ThisBlogThis!Share to TwitterShare to FacebookShare to Pinterest Labels: clojure, destructuring 10 comments:</p> <pre><code>fogus8:26 AM\n\nNice post. One other note that naturally follows from the end of your post is that destructuring forms the basis of Clojure's named arguments:\n\n(defn print-status [&amp; {name :name [hole1 hole2] :scores}]\n(println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))\n\n(print-status :name \"Joey\" :scores [42 18])\n\n\nYou can also use pre-conditions to check if certain arguments are passed in:\n\n\n(defn print-status [&amp; {name :name [hole1 hole2] :scores}]\n{:pre [name]}\n(println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))\n\n(print-status :scores [42 18])\n; java.lang.AssertionError: Assert failed: name\n\n(print-status :name \"Joey\" :scores [42 18])\n; name: Joey hole1: 42 hole2: 18\n\n\n:f\nReply\nJay Fields9:08 AM\n\nGood stuff Fogus, thanks.\n\nCheers, Jay\nReply\nMatt Todd5:31 PM\n\nCan you combine :as and :or et al?\nReply\nAnonymous7:29 PM\n\nYes, all the directives can be used at the same time.\n\nCheers, Jay\nReply\nLaurent PETIT3:08 AM\n</code></pre> <p>Hi, one note about using destructuring for function arguments : by doing so, you're quite explicitly establishing a more detailed contract with the consumer of the function. That is, you open the internals of the passed arguments.</p> <p>Depending on the fact that the user may or may not be aware of the internals of the arguments, it may or may not be a good idea.</p> <p>So I tend to think about the use of destructuring function arguments directly in the function signature, depending on whether the \"layout\" of the arguments of the function is part of the user API.     Reply</p>"},{"location":"reference/standard-library/destructuring/#clojure-destructuring-tutorial-and-cheat-sheet","title":"Clojure Destructuring Tutorial and Cheat Sheet","text":"<p>(Related blog post)</p> <p>Simply put, destructuring in Clojure is a way extract values from a data structure and bind them to symbols, without having to explicitly traverse the data structure. It allows for elegant and concise Clojure code.</p>"},{"location":"reference/standard-library/destructuring/#vectors","title":"Vectors","text":"<p>Syntax: <code>[symbol another-symbol] [\"value\" \"another-value\"]</code></p> <pre><code>(def my-vector [:a :b :c :d])\n(def my-nested-vector [:a :b :c :d [:x :y :z]])\n\n(let [[a b c d] my-vector]\n  (println a b c d))\n;; =&gt; :a :b :c :d\n\n(let [[a _ _ d [x y z]] my-nested-vector]\n  (println a d x y z))\n;; =&gt; :a :d :x :y :z\n</code></pre> <p>You don't have to match the full vector.</p> <pre><code>(let [[a b c] my-vector]\n  (println a b c))\n;; =&gt; :a :b :c\n</code></pre> <p>You can use <code>&amp; the-rest</code> to bind the remaining part of the vector to <code>the-rest</code>.</p> <pre><code>(let [[a b &amp; the-rest] my-vector]\n  (println a b the-rest))\n;; =&gt; :a :b (:c :d)\n</code></pre> <p>When a destructuring form \"exceeds\" a vector (i.e. there not enough items in the vector to bind to), the excess symbols will be bound to <code>nil</code>.</p> <pre><code>(let [[a b c d e f g] my-vector]\n  (println a b c d e f g))\n;; =&gt; :a :b :c :d nil nil nil\n</code></pre> <p>You can use <code>:as some-symbol</code> as the last two items in the destructuring form to bind the whole vector to <code>some-symbol</code></p> <pre><code>(let [[:as all] my-vector]\n  (println all))\n;; =&gt; [:a :b :c :d]\n\n(let [[a :as all] my-vector]\n  (println a all))\n;; =&gt; :a [:a :b :c :d]\n\n(let [[a _ _ _ [x y z :as nested] :as all] my-nested-vector]\n  (println a x y z nested all))\n;; =&gt; :a :x :y :z [:x :y :z] [:a :b :c :d [:x :y :z]]\n</code></pre> <p>You can use both <code>&amp; the-rest</code> and <code>:as some-symbol</code>.</p> <pre><code>(let [[a b &amp; the-rest :as all] my-vector]\n  (println a b the-rest all))\n;; =&gt; :a :b (:c :d) [:a :b :c :d]\n</code></pre>"},{"location":"reference/standard-library/destructuring/#optional-arguments-for-functions","title":"Optional arguments for functions","text":"<p>With destructuring and the <code>&amp; the-rest</code> form, you can specify optional arguments to functions.</p> <pre><code>(defn foo [a b &amp; more-args]\n  (println a b more-args))\n(foo :a :b) ;; =&gt; :a :b nil\n(foo :a :b :x) ;; =&gt; :a :b (:x)\n(foo :a :b :x :y :z) ;; =&gt; :a :b (:x :y :z)\n\n(defn foo [a b &amp; [x y z]]\n  (println a b x y z))\n(foo :a :b) ;; =&gt; :a :b nil nil nil\n(foo :a :b :x) ;; =&gt; :a :b :x nil nil\n(foo :a :b :x :y :z) ;; =&gt; :a :b :x :y :z\n</code></pre>"},{"location":"reference/standard-library/destructuring/#maps","title":"Maps","text":"<p>Syntax: <code>{symbol :key, another-symbol :another-key} {:key \"value\" :another-key \"another-value\"}</code></p> <pre><code>(def my-hashmap {:a \"A\" :b \"B\" :c \"C\" :d \"D\"})\n(def my-nested-hashmap {:a \"A\" :b \"B\" :c \"C\" :d \"D\" :q {:x \"X\" :y \"Y\" :z \"Z\"}})\n\n(let [{a :a d :d} my-hashmap]\n  (println a d))\n;; =&gt; A D\n\n(let [{a :a, b :b, {x :x, y :y} :q} my-nested-hashmap]\n  (println a b x y))\n;; =&gt; A B X Y\n</code></pre> <p>Similar to vectors, if a key is not found in the map, the symbol will be bound to <code>nil</code>.</p> <pre><code>(let [{a :a, not-found :not-found, b :b} my-hashmap]\n  (println a not-found b))\n;; =&gt; A nil B\n</code></pre> <p>You can provide an optional default value for these missing keys with the <code>:or</code> keyword and a map of default values.</p> <pre><code>(let [{a :a, not-found :not-found, b :b, :or {not-found \":)\"}} my-hashmap]\n  (println a not-found b))\n;; =&gt; A :) B\n</code></pre> <p>The <code>:as some-symbol</code> form is also available for maps, but unlike vectors it can be specified anywhere (but still preferred to be the last two pairs).</p> <pre><code>(let [{a :a, b :b, :as all} my-hashmap]\n  (println a b all))\n;; =&gt; A B {:a A :b B :c C :d D}\n</code></pre> <p>And combining <code>:as</code> and <code>:or</code> keywords (again, <code>:as</code> preferred to be the last).</p> <pre><code>(let [{a :a, b :b, not-found :not-found, :or {not-found \":)\"}, :as all} my-hashmap]\n  (println a b not-found all))\n;; =&gt; A B :) {:a A :b B :c C :d D}\n</code></pre> <p>There is no <code>&amp; the-rest</code> for maps.</p>"},{"location":"reference/standard-library/destructuring/#shortcuts","title":"Shortcuts","text":"<p>Having to specify <code>{symbol :symbol}</code> for each key is repetitive and verbose (it's almost always going to be the symbol equivalent of the key), so shortcuts are provided so you only have to type the symbol once.</p> <p>Here are all the previous examples using the <code>:keys</code> keyword followed by a vector of symbols:</p> <pre><code>(let [{:keys [a d]} my-hashmap]\n  (println a d))\n;; =&gt; A D\n\n(let [{:keys [a b], {:keys [x y]} :q} my-nested-hashmap]\n  (println a b x y))\n;; =&gt; A B X Y\n\n(let [{:keys [a not-found b]} my-hashmap]\n  (println a not-found b))\n;; =&gt; A nil B\n\n(let [{:keys [a not-found b], :or {not-found \":)\"}} my-hashmap]\n  (println a not-found b))\n;; =&gt; A :) B\n\n(let [{:keys [a b], :as all} my-hashmap]\n  (println a b all))\n;; =&gt; A B {:a A :b B :c C :d D}\n\n(let [{:keys [a b not-found], :or {not-found \":)\"}, :as all} my-hashmap]\n  (println a b not-found all))\n;; =&gt; A B :) {:a A :b B :c C :d D}\n</code></pre> <p>There are also <code>:strs</code> and <code>:syms</code> alternatives, for when your map has strings or symbols for keys (instead of keywords), respectively.</p> <pre><code>(let [{:strs [a d]} {\"a\" \"A\", \"b\" \"B\", \"c\" \"C\", \"d\" \"D\"}]\n  (println a d))\n;; =&gt; A D\n\n(let [{:syms [a d]} {'a \"A\", 'b \"B\", 'c \"C\", 'd \"D\"}]\n  (println a d))\n;; =&gt; A D\n</code></pre>"},{"location":"reference/standard-library/destructuring/#keyword-arguments-for-function","title":"Keyword arguments for function","text":"<p>Map destructuring also works with lists (but not vectors).</p> <pre><code>(let [{:keys [a b]} '(\"X\", \"Y\", :a \"A\", :b \"B\")]\n(println a b))\n;; =&gt; A B\n</code></pre> <p>This allows your functions to have optional keyword arguments.</p> <pre><code>(defn foo [a b &amp; {:keys [x y]}]\n  (println a b x y))\n(foo \"A\" \"B\")  ;; =&gt; A B nil nil\n(foo \"A\" \"B\" :x \"X\")  ;; =&gt; A B X nil\n(foo \"A\" \"B\" :x \"X\" :y \"Y\")  ;; =&gt; A B X Y\n</code></pre>"},{"location":"reference/standard-library/predicate-functions/","title":"Clojure Predicate functions","text":"<p>A predicate function takes a single argument and returns a truthy value, e.g. <code>true</code> or <code>false</code></p> <p></p> <p>There are over 70 predicate functions provided by the <code>clojure.core</code> namespace. </p> <code>clojure.core</code> predicates Description &gt;0? (^:private) &gt;1? (^:private) any? associative? boolean? bound? bytes? chunked-seq? (^:static) class? coll? contains? counted? decimal? delay? distinct? double? empty? even? every? false? fits-table? (defn-) float? fn? future? future-cancelled? future-done? ident? identical? ifn? indexed? inst? int? integer? isa? is-annotation? (defn-) is-runtime-annotation? (defn-) keyword? libspec? (defn-) list? map-entry? nat-int? neg? neg-int? nil? number? odd? pos? pos-int? qualified-ident? qualified-keyword? qualified-symbol? ratio? rational? reader-conditional? realized? reduced? reversible? seqable? sequential? set? simple-ident? simple-keyword? simple-symbol? some? sorted? special-symbol? symbol? tagged-literal? thread-bound? true? uri? uuid? var? volatile? zero?"},{"location":"reference/standard-library/sequences/","title":"Standard Library: Sequences","text":"<p>Functions to create and work with the Clojure sequences, including lists and sequence generators</p>"},{"location":"reference/standard-library/sequences/#sequence-access","title":"Sequence access","text":"Function Description <code>first</code> <code>second</code> <code>rest</code> <code>last</code> <code>butlast</code> <code>nth</code>"},{"location":"reference/standard-library/sequences/#infinite-sequence-generators","title":"Infinite sequence generators","text":"Function Description <code>range</code> <code>cycle</code> <code>iterate</code>"},{"location":"reference/standard-library/regular-expressions/","title":"Regular Expressions - regex","text":"<p>Regular expressions are a powerful and compact way to find specific patterns in text strings. Clojure provides a simple syntax for Java regex patterns.</p> <p><code>#\"pattern\"</code> is the literal representation of a regular expressions in Clojure, where <code>pattern</code> is the regular expression.</p> <p>Create regular expression pattern</p> <p><code>(re-pattern pattern)</code> will return the Clojure literal representation of a given regex pattern.</p> <p>A string can become a regular expression pattern, e.g. <code>\":\"</code> becomes the regex pattern <code>#\":\"</code> <pre><code>(re-pattern \":\")\n</code></pre></p> <p>The regular expression syntax cheatsheet by Mozilla is an excellent reference for regular expression patterns.</p>"},{"location":"reference/standard-library/regular-expressions/#regular-expressions-overview","title":"Regular expressions overview","text":"<p>Regular expressions in Clojure</p> <p> </p> <p>Find the most common word in a book using regular expressions</p> <p> </p> Double escaping not required <p>The Clojure syntax means you do not need to double escape special characters, eg. <code>\\\\</code>, and keeps the patterns clean and simple to read. In other languages, backslashes intended for consumption by the regex compiler must be doubled.</p> <pre><code>(java.util.regex.Pattern/compile \"\\\\d\")\n;;=&gt; #\"\\d\"\n</code></pre> <p>The rules for embedding unusual literal characters or predefined character classes are listed in the Javadoc for Pattern.</p>"},{"location":"reference/standard-library/regular-expressions/#host-platform-support","title":"Host platform support","text":"<p>Clojure runs on the Java Virtual Machine and uses Java regular expressions.</p> <p>Regular expressions in Clojure create a java.util.regex.Pattern type</p> <pre><code>(type #\"pattern\")\n;;=&gt; java.util.regex.Pattern\n</code></pre> <p>ClojureScript runs on JavaScript engines and uses Javascript regular expressions.</p>"},{"location":"reference/standard-library/regular-expressions/#option-flags","title":"Option flags","text":"<p>Regular expression option flags can make a pattern case-insensitive or enable multiline mode. Clojure's regex literals starting with (?) set the mode for the rest of the pattern. For example, the pattern <code>#\"(?i)yo\"</code> matches the strings <code>\u201cyo\u201d</code>, <code>\u201cyO\u201d</code>, <code>\u201cYo\u201d</code>, and <code>\u201cYO\u201d</code>. <p>Flags that can be used in Clojure regular-expression patterns, along with their long name and a description of what they do. See Java's documentation for the java.util.regex.Pattern class for more details.</p> Flag Flag Name Description d UNIX_LINES ., ^, and $ match only the Unix line terminator '\\n'. i CASE_INSENSITIVE ASCII characters are matched without regard to uppercase or lower-case. x COMMENTS Whitespace and comments in the pattern are ignored. m MULTILINE ^ and $ match near line terminators instead of only at the beginning or end of the entire input string. s DOTALL . matches any character including the line terminator. u UNICODE_CASE Causes the i flag to use Unicode case insensitivity instead of ASCII. <p>The re-seq function is Clojure's regex workhorse. It returns a lazy seq of all matches in a string, which means it can be used to efficiently test whether a string matches or to find all matches in a string or a mapped file:</p> <pre><code>(re-seq #\"\\w+\" \"one-two/three\")\n;;=&gt; (\"one\" \"two\" \"three\")\n</code></pre> <p>The preceding regular expression has no capturing groups, so each match in the returned seq is a string. A capturing group (subsegments that are accessible via the returned match object) in the regex causes each returned item to be a vector:</p> <pre><code>(re-seq #\"\\w*(\\w)\" \"one-two/three\")\n([\"one\" \"e\"] [\"two\" \"o\"] [\"three\" \"e\"])\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/#references","title":"References","text":"<p>4Clojure #37 - regular expressions Regex in Clojure - purelyfunctional.tv</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/","title":"Common Regular Expression patterns","text":"<p>Common string formats used in software development and examples of regular expressions to check their correctness.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#username-regular-expression-pattern","title":"Username Regular Expression Pattern","text":"<p>A 8 to 24 character passwords that can include any lower case character or digit (number).  Only the underscore and dash special characters can be used.</p> <pre><code>(re-matches #\"^[a-z0-9_-]{8,24}$\" \"good-username\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^[a-z0-9_-]{8,24}$\n\n^                    # Start of the line\n  [a-z0-9_-]         # Match characters and symbols in the list, a-z, 0-9 , underscore , hyphen\n             {8,24}  # Length at least 8 characters and maximum length of 24\n$                    # End of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#password-regular-expression-pattern","title":"Password Regular Expression Pattern","text":"<p>A password should be 8 to 24 character string with at least one digit, one upper case letter, one lower case letter and one special symbol, <code>@#$%</code>.</p> <pre><code>(re-matches #\"((?=.*\\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%]).{8,24})\" \"G00d @ username\")\n</code></pre> <p>The order of the grouping formulas does not matter</p> <p>Breakdown the regex pattern:</p> <pre><code>((?=.*\\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%]).{8,24})\n\n(   # Start of group\n  (?=.*\\d)  #   must contains one digit from 0-9\n  (?=.*[a-z])  #   must contains one lowercase characters\n  (?=.*[A-Z])  #   must contains one uppercase characters\n  (?=.*[@#$%])  #   must contains one special symbols in the list \"@#$%\"\n              .  #     match anything with previous condition checking\n                {8,24} #        length at least 8 characters and maximum of 24\n)   # End of group\n</code></pre> <p><code>?=</code> means apply the assertion condition, which is meaningless by itself and works in combination with others.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hexadecimal-color-code-regular-expression-pattern","title":"Hexadecimal Color Code Regular Expression Pattern","text":"<p>The string must start with a <code>#</code>symbol , follow by a letter from <code>a</code> to <code>f</code>, <code>A</code> to <code>Z</code> or a digit from <code>0</code> to <code>9</code> with a length of exactly 3 or 6.` This regular expression pattern is very useful for the Hexadecimal web colors code checking.</p> <pre><code>(re-matches #\"^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$\" \"#FFAABB\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$\n\n^   #start of the line\n #   #  must contain a \"#\" symbols\n (   #  start of group #1\n  [A-Fa-f0-9]{3} #    any strings in the list, with length of 3\n  |   #    ..or\n  [A-Fa-f0-9]{6} #    any strings in the list, with length of 6\n )   #  end of group #1\n$   #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#email-regular-expression-pattern","title":"Email Regular Expression Pattern","text":"<p>The account side of an email address starts with <code>_A-Za-z0-9-\\\\+</code> optional follow by <code>.[_A-Za-z0-9-]</code>, ending with an <code>@</code> symbol.</p> <p>The  domain starts with <code>A-Za-z0-9-</code>, follow by first level domain, e.g <code>.org</code>, <code>.io</code> and <code>.[A-Za-z0-9]</code> optionally follow by a second level domain, e.g. <code>.ac.uk</code>, <code>.com.au</code> or  <code>\\\\.[A-Za-z]{2,}</code>, where second level domain must start with a dot <code>.</code> and length must equal or more than 2 characters.</p> <pre><code>(re-matches\n  #\"^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$\"\n  \"jenny.jenn@jetpack.com.au\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^[_A-Za-z0-9-]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\\\\.[A-Za-z0-9]+)*(\\\\.[A-Za-z]{2,})$\n\n^   #start of the line\n  [_A-Za-z0-9-]+ #  must start with string in the bracket [ ], must contains one or more (+)\n  (   #  start of group #1\n    \\\\.[_A-Za-z0-9-]+ #     follow by a dot \".\" and string in the bracket [ ], must contains one or more (+)\n  )*   #  end of group #1, this group is optional (*)\n    @   #     must contains a \"@\" symbol\n     [A-Za-z0-9]+       #        follow by string in the bracket [ ], must contains one or more (+)\n      (   #    start of group #2 - first level TLD checking\n       \\\\.[A-Za-z0-9]+  #        follow by a dot \".\" and string in the bracket [ ], must contains one or more (+)\n      )*  #    end of group #2, this group is optional (*)\n      (   #    start of group #3 - second level TLD checking\n       \\\\.[A-Za-z]{2,}  #        follow by a dot \".\" and string in the bracket [ ], with minimum length of 2\n      )   #    end of group #3\n$   #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hintdouble-escaping-special-characters","title":"Hint::Double escaping special characters","text":"<p>Double escaping of special characters is not required in the Clojure syntax.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#image-file-name-and-extension-regular-expression-pattern","title":"Image File name and Extension Regular Expression Pattern","text":"<p>A file extension name is 1 or more characters without white space, follow by dot <code>.</code> and string end in <code>jpg</code> or <code>png</code> or <code>gif</code> or <code>bmp</code>.  The file name extension is case-insensitive.</p> <p>Change the combination <code>(jpg|png|gif|bmp)</code> for other file extension.</p> <pre><code>(re-matches #\"(?i)([^\\s]+(\\.(jpg|png|gif|bmp))$)\" \"clojure-logo.png\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>([^\\s]+(\\.(?i)(jpg|png|gif|bmp))$)\n\n(   #Start of the group #1\n [^\\s]+   #  must contains one or more anything (except white space)\n       (  #    start of the group #2\n         \\.  # follow by a dot \".\"\n         (?i)  # ignore the case sensitive checking\n             (  #   start of the group #3\n              jpg #       contains characters \"jpg\"\n              |  #       ..or\n              png #       contains characters \"png\"\n              |  #       ..or\n              gif #       contains characters \"gif\"\n              |  #       ..or\n              bmp #       contains characters \"bmp\"\n             )  #   end of the group #3\n       )  #     end of the group #2\n  $   #  end of the string\n)   #end of the group #1\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hintin-line-modifiers-not-supported-in-javascript","title":"Hint::in-line modifiers not supported in JavaScript","text":"<p>The REPL above uses ClojureScript, hosted on JavaScript. JavaScript does not support in-line modifier flags such as <code>(?i)</code> for a case insensitive pattern.  In-line flags will be converted by the ClojureScript reader if they are the first element in the literal regular expression pattern, or if the <code>js/RegExp</code> function is used to create the regular expression.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#ip-address-regular-expression-pattern","title":"IP Address Regular Expression Pattern","text":"<p>An IP address comprises of 4 groups of numbers between 0 and 255, with each group separated by a dot.</p> <p>Example IP address are: <code>192.168.0.1</code>, <code>127.0.0.1</code>, <code>192.120.240.100</code></p> <pre><code>(re-matches\n  #\"^([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])$\"\n  \"192.168.0.1\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.\n([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])$\n\n^  #start of the line\n (  #  start of group #1\n   [01]?\\\\d\\\\d? #    Can be one or two digits. If three digits appear, it must start either 0 or 1\n        #    e.g ([0-9], [0-9][0-9],[0-1][0-9][0-9])\n    |  #    ...or\n   2[0-4]\\\\d #    start with 2, follow by 0-4 and end with any digit (2[0-4][0-9])\n    |           #    ...or\n   25[0-5]      #    start with 2, follow by 5 and end with 0-5 (25[0-5])\n )  #  end of group #2\n  \\.            #  follow by a dot \".\"\n....            # repeat with 3 time (3x)\n$  #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#time-format-regular-expression-pattern","title":"Time Format Regular Expression Pattern","text":"<p>Time in 12-Hour Format Regular Expression Pattern.  The 12-hour clock format start between 0-12, then a semi colon, <code>:</code>, follow by <code>00-59</code>.  The pattern ends with <code>am</code> or <code>pm</code>.</p> <pre><code>(re-matches #\"(?i)(1[012]|[1-9]):[0-5][0-9](\\s)?(am|pm)\" \"12:59am\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>(1[012]|[1-9]):[0-5][0-9](\\\\s)?(?i)(am|pm)\n\n(    #start of group #1\n 1[012]    #  start with 10, 11, 12\n |    #  or\n [1-9]    #  start with 1,2,...9\n)    #end of group #1\n :    #    follow by a semi colon (:)\n  [0-5][0-9]   #   follow by 0..5 and 0..9, which means 00 to 59\n            (\\\\s)?  #        follow by a white space (optional)\n                  (?i)  #          next checking is case insensitive\n                      (am|pm) #            follow by am or pm\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#time-in-24-hour-format-regular-expression-pattern","title":"Time in 24-Hour Format Regular Expression Pattern","text":"<p>The 24-hour clock format start between 0-23 or 00-23, then a semi colon <code>:</code> and follow by 00-59.</p> <pre><code>(re-matches #\"(([01]?[0-9]|2[0-3]):[0-5][0-9])\" \"23:58\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>([01]?[0-9]|2[0-3]):[0-5][0-9]\n\n(    #start of group #1\n [01]?[0-9]   #  start with 0-9,1-9,00-09,10-19\n |    #  or\n 2[0-3]    #  start with 20-23\n)    #end of group #1\n :    #  follow by a semi colon (:)\n  [0-5][0-9]   #    follow by 0..5 and 0..9, which means 00 to 59\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#date-format-ddmmyyyy-regular-expression-pattern","title":"Date Format (dd/mm/yyyy) Regular Expression Pattern","text":"<p>Date format in the form <code>dd/mm/yyyy</code>. Validating a leap year and if there is 30 or 31 days in a month is not simple though.</p> <pre><code>(re-matches #\"(0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\\d\\d)\" \"20/02/2020\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>(0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\\\\d\\\\d)\n\n(   #start of group #1\n 0?[1-9]  #  01-09 or 1-9\n |                      #  ..or\n [12][0-9]  #  10-19 or 20-29\n |   #  ..or\n 3[01]   #  30, 31\n)           #end of group #1\n  /   #  follow by a \"/\"\n   (   #    start of group #2\n    0?[1-9]  # 01-09 or 1-9\n    |   # ..or\n    1[012]  # 10,11,12\n    )   #    end of group #2\n     /   # follow by a \"/\"\n      (   #   start of group #3\n       (19|20)\\\\d\\\\d #       19[0-9][0-9] or 20[0-9][0-9]\n       )  #   end of group #3\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#reference","title":"Reference","text":"<ul> <li>https://mkyong.com/regular-expressions/10-java-regular-expression-examples-you-should-know</li> </ul>"},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/","title":"Matching sub sequences","text":""},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/#matching-sub-sequences","title":"Matching sub-sequences","text":"<p><code>re-seq</code> returns a lazy seq of all of the matches. The elements of the seq are the results that <code>re-find</code> would return.</p> <p><pre><code>(re-seq #\"s+\" \"Helloween\")\n</code></pre> </p>"},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/#most-common-word","title":"Most common word","text":"<p><code>re-seq</code> is used in the most common word challenge to split a string into individual words.</p> <p>Extract from Project Guttenburg the text of The importance of being Earnest by Oscar Wilde.  This returns a string of the whole book.</p> <p>The book is broken down into a collection of individual words using <code>re-seq</code> and a regular expression pattern.</p> <p>The collection of words is converted to lower case, so that <code>The</code> and <code>the</code> are not counted as separate words. <code>frequencies</code> returns a collection of tuples, each tuple being a word and a value representing how often it occurs.  This collection is sorted by the value in descending order to show the word with the most occurrences at the top.</p> <pre><code>(-&gt;&gt; (slurp \"http://www.gutenberg.org/cache/epub/844/pg844.txt\")\n     (re-seq #\"[a-zA-Z0-9|']+\")\n     (map #(clojure.string/lower-case %))\n     frequencies\n     (sort-by val dec))\n</code></pre> <p>TODO: add link to complete example.</p>"},{"location":"reference/standard-library/regular-expressions/matching-sub-strings/","title":"Matching sub strings","text":""},{"location":"reference/standard-library/regular-expressions/matching-sub-strings/#matching-sub-strings","title":"Matching sub-strings","text":"<p><code>re-find</code> returns the first match within the string, using return values similar to re-matches.</p> <p><code>nil</code> is returned when the pattern does not find a match.</p> <pre><code>(re-find #\"pump\" \"Halloween\")\n</code></pre> <p>A matching pattern without groups returns the matched string</p> <pre><code>(re-find #\"e+\" \"Halloween\")\n</code></pre> <p>Match with groups returns a vector of results</p> <p><pre><code>(re-find #\"s+(.*)(s+)\" \"success\")\n</code></pre> </p>"},{"location":"reference/standard-library/regular-expressions/matching-with-groups/","title":"Matching with regex groups","text":"<p><code>rematches</code> takes a pattern and compares it with a string.</p> <p>If the pattern does not match the string then <code>nil</code> is returned to show the function returned a false value.</p> <pre><code>(re-matches #\"pumpkin\" \"Halloween pumpkin\")\n ```\n\nIf there is an exact match and there are no groups (parens) in the regex, then the matched string is returned.\n\n```clojure\n(re-matches #\"pumpkin\" \"pumpkin\")\n</code></pre> <p>If the pattern matches but there are groups, a vector of matching strings is returned. The first element in the vector is the entire match. The remaining elements are the group matches.</p> <pre><code>(re-matches #\"Halloween(.*)\" \"Halloween pumpkin\")\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/string-replace-with-regex/","title":"String replace with regex","text":""},{"location":"reference/standard-library/regular-expressions/string-replace-with-regex/#string-replace-with-regex-pattern","title":"String replace with regex pattern","text":"<p><code>clojure.string/replace</code> takes a string, a pattern and a substring that will replace matching patterns.</p> <pre><code>(clojure.string/replace \"mississippi\" #\"i..\" \"obb\")\n</code></pre> <p>Groups can be referred to in the substring replacement</p> <p><pre><code>(clojure.string/replace \"mississippi\" #\"(i)\" \"$1$1\")\n</code></pre> </p> <p>Replace with the value of a function applied to the match:</p> <pre><code>(clojure.string/replace \"mississippi\" #\"(.)i(.)\"\n     (fn [[_ b a]]\n       (str (clojure.string/upper-case b)\n            \"--\"\n            (clojure.string/upper-case a))))\n   \"M--SS--SS--Ppi\"\n</code></pre> <p><code>clojure.string/replace-first</code> is a variation where just the first occurrence is replaced.</p>"},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/","title":"String split with regex","text":""},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/#string-splitting-using-a-regex-pattern","title":"String splitting using a regex pattern","text":"<p><code>clojure.string/split</code> takes a string to be split and a pattern to split the string with.</p> <pre><code>(clojure.string/split \"This is a string    that I am splitting.\" #\"\\s+\")\n   [\"This\" \"is\" \"a\" \"string\" \"that\" \"I\" \"am\" \"splitting.\"]\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/#most-common-words-example","title":"Most common words example","text":"<p>Extract a list of the most commonly used English words, returned as a string of words that are separated by a comma.</p> <p>The <code>#\",\"</code> regex pattern splits the string of words to form a collection of individual words, each word being its own string.</p> <pre><code>(def common-english-words\n  (set\n    (clojure.string/split\n      (slurp\n        \"http://www.textfixer.com/resources/common-english-words.txt\")\n      #\",\")))\n</code></pre> <p>TODO: add link to complete example.</p>"},{"location":"reference/standard-library/regular-expressions/sub-expression-matches/","title":"Sub-expression Matches","text":"Pattern Description ^ Matches beginning of line. $ Matches end of line. . Matches any single character except newline. Using m option allows it to match newline as well. [...] Matches any single character in brackets. [^...] Matches any single character not in brackets \\A Beginning of entire string \\z End of entire string \\Z End of entire string except allowable final line terminator. re* Matches 0 or more occurrences of preceding expression. re+ Matches 1 or more of the previous thing re? Matches 0 or 1 occurrence of preceding expression. re{ n} Matches exactly n number of occurrences of preceding expression. re{ n,} Matches n or more occurrences of preceding expression. re{ n, m} Matches at least n and at most m occurrences of preceding expression. a b (re) Groups regular expressions and remembers matched text. (?: re) Groups regular expressions without remembering matched text. (?&gt; re) Matches independent pattern without backtracking. \\w Matches word characters. \\W Matches nonword characters. \\s Matches whitespace. Equivalent to [\\t\\n\\r\\f]. \\S Matches nonwhitespace. \\d Matches digits. Equivalent to [0-9]. \\D Matches nondigits. \\A Matches beginning of string. \\Z Matches end of string. If a newline exists, it matches just before newline. \\z Matches end of string. \\G Matches point where last match finished. \\n Back-reference to capture group number \"n\" \\b Matches word boundaries when outside brackets. Matches backspace (0x08) when inside brackets. \\B Matches nonword boundaries. \\n, \\t, etc. Matches newlines, carriage returns, tabs, etc. \\Q Escape (quote) all characters up to \\E \\E Ends quoting begun with \\Q"},{"location":"reference/tagged-literals/","title":"Tagged Literals","text":"<p>Frequently used value types are afforded a \"tagged literal\" syntax. It is similar to a constructor, but this special syntax makes it de/serializable and easier to read at the REPL.</p> <p>Tagged literals start with a # followed by a symbol and a literal:</p> <p><code>#js [...]</code>- JavaScript array literal</p> <p><code>#js {...}</code> - JavaScript object literal</p> <p><code>#inst \"...\"</code> - JavaScript date literal</p> <p><code>#uuid \"...\"</code> - UUID literal</p> <p><code>#queue [...]</code> - queue literal</p>"},{"location":"reference/tagged-literals/uuid/","title":"uuid tag literal","text":"<p>A universally unique identifier (UUID).</p> <pre><code>#uuid \"8-4-4-4-12\" - numbers represent the number of hex digits\n#uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\" - actual example\n</code></pre> <p>Representing UUIDs with #uuid rather than just a plain string has the following benefits:</p> <pre><code>the reader will throw an exception on malformed UUIDs\nits UUID type is preserved and shown when serialized to edn.\n</code></pre>"},{"location":"reference/tagged-literals/uuid/#creating-uuids-clojure","title":"Creating UUIDs - Clojure","text":"<p>In Clojure, call the randomUUID method of the java.util.UUID class</p> <pre><code>(java.util.UUID/randomUUID)\n</code></pre> <p>This returns a UUID tagged literal.</p> <pre><code>(java.util.UUID/randomUUID)\n;; =&gt; #uuid \"44f3ffd7-6702-4b8a-af25-11bee4b5ec4f\"\n</code></pre> <p>Looking at the type we can see its a Java object from the java.util.UUID class:</p> <pre><code>(type (java.util.UUID/randomUUID))\n;; =&gt; java.util.UUID\n</code></pre>"},{"location":"reference/tagged-literals/uuid/#creating-uuids-clojurescript","title":"Creating UUIDs - ClojureScript","text":"<p>Randomly generate a UUID in ClojureScript:</p> <p><code>cljs.core/random-uuid</code></p> <p>To label a value as a UUID:</p> <p><code>cljs.core/uuid</code></p>"},{"location":"reference/tagged-literals/uuid/#hintuuid-does-not-validate-the-value","title":"Hint::uuid does not validate the value","text":"<p>The ClojureScript documentation states that uuid? does not perform validation.</p>"},{"location":"reference/tagged-literals/uuid/#testing-for-a-uuid","title":"Testing for a uuid","text":"<p><code>uuid?</code> tests a given value and returns true if it is a uuid tagged literal value.</p> <p><code>tagged-literal?</code> is the more general function for any tagged values.</p>"},{"location":"simple-projects/","title":"Small Projects","text":"<p>An effective way to get comfortable with Clojure is to start writing small projects.  In this section several small projects are used to walk the audience through how to create and develop a project, as well as learn some Clojure functions and functional programming techniques along the way.</p> Project Topics Description Random Clojure Function namespace vars print a random function from the Clojure standard library Encoding and decoding hash-map dictionaries transforming messages between one form and another Data Transformation transforming larger and larger data sets Test Driven Development and Kata Unit testing Unit testing and solving challenges using different approaches <p>Create a Clojure project</p> <p>Clojure CLI tools and clj-new to create a new Clojure project.</p>"},{"location":"simple-projects/generate-web-page/","title":"Generate Web Page","text":"<p>Generate a web page from Clojure code, using Hiccup</p> <p>Generate a full HTML webpage with content.</p> <p>Add a CSS library (bulma.io, bootstrap) to improve generation</p>"},{"location":"simple-projects/generate-web-page/#summary","title":"Summary","text":"<p>Generating a web page in Clojure shows how easy it is to structure data and transform that data into other structures.</p> <p>Although this kind of project is easy enough to just do in a REPL directly, using a Clojure aware editor with a Clojure project makes changes to the code far simpler, without loosing any of the immediate feedback of the REPL.</p> <p>Most Clojure developers use the REPL by evaluating code in the editor showing the source code from the project.</p> <p> Practicalli Web Services book shows how to build websites, create self-documented API's, manage Web Application servers and use databases to persist data.</p>"},{"location":"simple-projects/random-clojure-function/","title":"Random Clojure Function","text":"<p>A simple application that returns a random function from the <code>clojure.core</code> namespace, along with the function argument list and its description (from the doc-string)</p> <p>There are 659 functions in <code>clojure.core</code> namespace and 955 in the standard library (as of June 2020).  These functions are learned over time as experience is gained with Clojure.</p> Project: Random Clojure function <p> practicalli/random-clojure-function repository contains a Clojure project with an example solution</p>"},{"location":"simple-projects/random-clojure-function/#live-coding-video-walk-through","title":"Live Coding Video walk-through","text":"<p>A Live coding video walk-through of this project shows how this application was developed, using Spacemacs editor and CircleCI for continuous integration.</p>  -M flag superseeds -A flag <p>The <code>-M</code> flag replaced the <code>-A</code> flag when running code via <code>clojure.main</code>, e.g. when an alias contains <code>:main-opts</code>.  The <code>-A</code> flag should be used only for the specific case of including an alias when starting the Clojure CLI built-in REPL.</p> <p> </p>"},{"location":"simple-projects/random-clojure-function/#create-a-project","title":"Create a project","text":"<p>Use the <code>:project/create</code>  Practicalli Clojure CLI Config to create a new Clojure project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/random-function\n</code></pre> <p>This project has a <code>deps.edn</code> file that includes the aliases</p> <ul> <li><code>:test</code> - includes the <code>test/</code> directory in the class path so unit test code is found</li> <li><code>:runner</code> to run the Cognitect Labs test runner which will find and run all unit tests</li> </ul>"},{"location":"simple-projects/random-clojure-function/#repl-experiments","title":"REPL experiments","text":"<p>Open the project in a Clojure-aware editor or start a Rebel terminal UI REPL</p> Clojure EditorRebel REPL <p>Open the <code>src/practicalli/random-function.clj</code> file in a Clojure aware editor and start a REPL process (jack-in)</p> <p>Optionally create a rich comment form that will contain the expressions as the design of the code evolves, moving completed functions out of the comment forms so they can be run by evaluating the whole namespace. <pre><code>(ns practicalli.random-function)\n\n(comment\n  ;; add experimental code here\n)\n</code></pre></p> <p>Open a terminal and change to the root of the Clojure project created, i.e. the directory that contains the <code>deps.edn</code> file.</p> <p>Start a REPL that provides a rich terminal UI <pre><code>clojure -M:repl/reloaded\n</code></pre> <code>require</code> will make a namespace available from within the REPL <pre><code>(require '[practicalli.random-function])\n</code></pre> Change into the <code>random-function</code> namespace to define functions <pre><code>(in-ns 'practicalli.random-function')\n</code></pre> Reload changes made to the <code>src/practicalli/random_function.clj</code> file using the <code>require</code> function with the <code>:reload</code> option.  <code>:reload</code> forces the loading of all the definitions in the namespace file, overriding any functions of the same name in the REPL. <pre><code>(require '[practicalli.random-function] :reload)\n</code></pre></p> <p>Copy finished code into the source code files</p> <p>Assuming the code should be kept after the REPL is closed, save the finished versions of function definitions into the source code files.  Use Up and Down keys at the REPL prompt to navigate the history of expressions</p> <p>List all the public functions in the <code>clojure.core</code> namespace using the <code>ns-publics</code> function</p> <pre><code>(ns-publics 'clojure.core)\n</code></pre> <p>The hash-map keys are function symbols and the values are the function vars</p> <pre><code>{+' #'clojure.core/+',\n decimal? #'clojure.core/decimal?,\n sort-by #'clojure.core/sort-by,\n macroexpand #'clojure.core/macroexpand\n ,,,}\n</code></pre> <p>The <code>meta</code> function will return a hash-map of details about a function, when given a function var.</p> <pre><code>(meta #'map)\n</code></pre> <p>The hash-map has several useful pieces of information for the application, including <code>:name</code>, <code>:doc</code>, and <code>:arglists</code></p> <pre><code>;; =&gt; {:added \"1.0\",\n;;     :ns #namespace[clojure.core],\n;;     :name map,\n;;     :file \"clojure/core.clj\",\n;;     :static true,\n;;     :column 1,\n;;     :line 2727,\n;;     :arglists ([f] [f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 &amp; colls]),\n;;     :doc\n;;     \"Returns a lazy sequence consisting of the result of applying f to\\n  the set of first items of each coll, followed by applying f to the\\n  set of second items in each coll, until any one of the colls is\\n  exhausted.  Any remaining items in other colls are ignored. Function\\n  f should accept number-of-colls arguments. Returns a transducer when\\n  no collection is provided.\"}\n</code></pre> <p>To use the <code>meta</code> function, the values from the <code>ns-publics</code> results should be used.</p> <pre><code>(vals (ns-publics 'clojure.core))\n</code></pre> <p><code>rand-nth</code> will return a random function var from the sequence of function vars</p> <pre><code>(rand-nth (vals (ns-publics 'clojure.core)))\n</code></pre> <p>A single function var is returned, so then the specific meta data can be returned.</p> <pre><code>(meta (rand-nth (vals (ns-publics 'clojure.core))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#define-a-name-for-all-functions","title":"Define a name for all functions","text":"<p>Edit the <code>src/practicalli/random-function.clj</code> file and define a name for the collection of all public functions from <code>clojure.core</code></p> <pre><code>(def standard-library\n  \"Fully qualified function names from clojure.core\"\n  (vals (ns-publics 'clojure.core)))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#write-unit-tests","title":"Write Unit Tests","text":"<p>From the REPL experiments we have a basic approach for the application design, so codify that design by writing unit tests.  This will also highlight regressions during the course of development.</p> <p>Edit the file <code>test/practicalli/random_function_test.clj</code> and add unit tests.</p> <p>The first test check the standard-library-functions contains entries.</p> <p>The second test checks the -main function returns a string (the function name and details).</p> src/practicalli/random_function_test.clj<pre><code>(ns practicalli.random-function-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [practicalli.random-function :as random-fn]))\n\n(deftest standard-library-test\n  (testing \"Show random function from Clojure standard library\"\n    (is (seq random-fn/standard-library-functions))\n    (is (string? (random-fn/-main)))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#update-the-main-function","title":"Update the main function","text":"<p>Edit the <code>src/practicalli/random-function.clj</code> file.  Change the <code>-main</code> function to return a string of the function name and description.</p> src/practicalli/random-function.clj<pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (let [function-details (meta (rand-nth standard-library-functions))]\n    (str (function-details :name) \"\\n  \" (function-details :doc)))\n  )\n</code></pre> Cognitect Test Runner <p>Run the tests with the Congnitect test runner via the <code>test</code> function in the <code>build.clj</code> file. ```shell clojure -T:build test</p> <p>```</p> Kaocha Test Runner <p>Run the tests with the Kaocha test runner using the alias <code>:test/run</code> from Practicalli Clojure CLI config ```shell clojure -M:test/run</p> <p>```</p>"},{"location":"simple-projects/random-clojure-function/#running-the-application","title":"Running the application","text":"<p>Use the clojure command with the main namespace of the application.  Clojure will look for the -main function and evaluate it.</p> <pre><code>clojure -M -m practicalli.random-function\n</code></pre> <p>This should return a random function name and its description.  However, nothing is returned.  Time to refactor the code.</p>"},{"location":"simple-projects/random-clojure-function/#improving-the-code","title":"Improving the code","text":"<p>The tests pass, however, no output is shown when the application is run.</p> <p>The main function returns a string but nothing is sent to standard out, so running the application does not return anything.</p> <p>The <code>str</code> expression could be wrapped in a println, although that would make the result harder to test and not be very clean code.  Refactor the <code>-main</code> to a specific function seems appropriate.</p> <p>Replace the <code>-main-test</code> with a <code>random-function-test</code> that will be used to test a new function of the same name which will be used for retrieving the random Clojure function.</p> <pre><code>(deftest random-function-test\n  (testing \"Show random function from Clojure standard library\"\n    (is (seq SUT/standard-library-functions))\n    (is (string? (SUT/random-function SUT/standard-library-functions)))))\n</code></pre> <p>Create a new function to return a random function from a given collection of functions, essentially moving the code from <code>-main</code>.</p> <p>The function extracts the function <code>:name</code> and <code>:doc</code> from the metadata of the randomly chosen function.</p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :name) \"\\n  \" (function-details :doc) \"\\n  \")))\n</code></pre> <p>Update the main function to call this new function.</p> <pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (println (random-function standard-library-functions)))\n</code></pre> <p>Run the tests again.</p> <p>If the tests pass, then run the application again</p> <pre><code> clojure -M -m practicalli.random-function\n</code></pre> <p>A random function and its description are displayed.</p>"},{"location":"simple-projects/random-clojure-function/#adding-the-function-signature","title":"Adding the function signature","text":"<p>Edit the <code>random-function</code> code and add the function signature to the string returned by the application.</p> <p>Format the code so it is in the same structure of the output it produces, making the code clearer to understand.</p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :name)\n    \"\\n  \" (function-details :doc)\n    \"\\n  \" (function-details :arglists))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#add-more-namespaces","title":"Add more namespaces","text":"<p>All current namespaces on the classpath can be retrieved using the <code>all-ns</code> function.  This returns a lazy-seq, <code>(type (all-ns))</code></p> <pre><code>(all-ns)\n</code></pre> <p>Using the list of namespace the <code>ns-publics</code> can retrieve all functions across all namespaces.</p> <p>Create a helper function to get the functions from a namespace, as this is going to be used in several places.</p> <pre><code>(defn function-list\n  [namespace]\n  (vals (ns-publics namespace)))\n</code></pre> <p>This function can be mapped over all the namespaces to get a sequence of all function vars.  Using <code>map</code> creates a sequence for each namespace, returned as a sequence of sequences.  Using <code>mapcat</code> will concatenate the nested sequences and return a flat sequence of function vars.</p> <pre><code>(mapcat #(vals (ns-publics %)) (all-ns))\n</code></pre> <p>Bind the results of this expression to the name <code>all-public-functions</code>.</p> <pre><code>(def available-namespaces\n  (mapcat #(vals (ns-publics %)) (all-ns)))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#control-which-namespaces-are-consulted","title":"Control which namespaces are consulted","text":"<p>There is no way to control which library we get the functions from, limiting the ability of our application.</p> <p>Refactor the main namespace to act differently based on arguments passed:</p> <ol> <li> <p>If no arguments are passed then all public functions are used to pull a random function from.</p> </li> <li> <p>If any argument is passed, the argument should be used as the namespace to pull a random function from.  The argument is assumed to be a string.</p> </li> </ol> <p><code>ns-publics</code> function needs a namespace as a symbol, so the <code>symbol</code> function is used to convert the argument.</p> <pre><code>(symbol \"clojure.string\")\n</code></pre> <p>The <code>-main</code> function uses <code>[&amp; args]</code> as a means to take multiple arguments. All arguments are put into a vector, so the symbol function should be mapped over the elements in the vector to create symbols for all the namespaces.</p> <p>Use an anonymous function to convert the arguments to symbols and retrieve the list of public functions from each namespace.  This saves mapping over the arguments twice.</p> <p><code>mapcat</code> the function-list function over all the namespaces, converting each namespace to a symbol.</p> <pre><code>(mapcat #(function-list (symbol %)) args)\n</code></pre> <p>Update the main function with an if statement.  Use <code>seq</code> as the condition to test if a sequence (the argument vector) has any elements (namespaces to use).</p> <p>If there are arguments, then get the functions for the specific namespaces.</p> <p>Else return all the functions from all the namespaces.</p> <pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (if (seq args)\n    (println (random-function (mapcat #(function-list (symbol %)) args)))\n    (println (random-function standard-library-functions))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#use-the-fully-qualified-name-for-the-namespace","title":"Use the fully qualified name for the namespace","text":"<p>Now that functions can come from a range of namespaces, the fully qualified namespace should be used for the function, eg. domain/namespace</p> <pre><code>(:ns (meta (rand-nth standard-library-functions)))\n</code></pre> <p>Update the random function to return the domain part of the namespace, separated by a <code>/</code></p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :ns) \"/\" (function-details :name)\n         \"\\n  \" (function-details :arglists)\n         \"\\n  \" (function-details :doc))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#use-all-available-namespaces-by-default","title":"Use all available namespaces by default","text":"<p>Define a name to represent the collection of all available namespaces, in the context of the running REPL.</p> <pre><code>(def all-public-functions\n  \"Fully qualified function names from available\"\n  (mapcat #(vals (ns-publics %)) (all-ns)))\n</code></pre> <p>Update the <code>-main</code> function to use all available namespaces if no arguments are passed to the main function.</p> <pre><code>(defn -main\n  \"Return a random function and its details\n  from the available namespaces\"\n  [&amp; args]\n  (if (seq args)\n    (println (random-function (mapcat #(function-list (symbol %)) args)))\n    (println (random-function all-public-functions))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#follow-on-idea-convert-to-a-web-service","title":"Follow-on idea: Convert to a web service","text":"<p>Add http-kit server and send  information back as a plain text, html, json and edn</p>"},{"location":"simple-projects/random-clojure-function/#follow-on-idea-convert-to-a-library","title":"Follow-on idea: Convert to a library","text":"<p>Convert the project to a library so this feature can be used as a development tool for any project.</p> <p>Add functionality to list all functions from all namespaces or a specific namespace, or functions from all namespaces of a particular domain, e.g <code>practicalli</code> or <code>practicalli.app</code></p>"},{"location":"simple-projects/split-the-bill/","title":"Split the bill","text":"<p>In a restaurant a group of friends and relatives are having a reunion dinner after a year of not seeing each other.</p> <p>Once the meal comes to an end, its time to pay the bill.  So how would you write code to split the bill?</p> <p>Start with the simplest possible approach, with everyone paying the same.</p>"},{"location":"simple-projects/split-the-bill/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/split-the-bill\n</code></pre> <pre><code>(str \"Create code to calculate the bill, including what each person should pay\")\n</code></pre> <p>Tke a look at the Who am I section for ideas on how to model the bill.  Also look at More Than Average for ideas on how to write code to work out how to pay the bill.</p>"},{"location":"simple-projects/split-the-bill/#paying-what-was-ordered","title":"Paying what was ordered","text":"<p>As not everyone had eaten the same amount of food or arrived at the same time, then there was an ask for everyone to pay just what they ordered.</p> <p>So create a collection to capture what each person ordered and create an itemised bill so each person knows what they should pay.</p> <p>Define a detailed bill based on what each person ordered, then create an itemised bill based on each persons order</p> <p>Now it was realised that what everyone ordered is not what everyone ate.  So now we need to take the order and create an itemised bill based on what everyone actually ate (lets suspend believe here a little and assume everyone knows exactly what they ate, and is honest about it).</p> <p>Define a detailed bill based on what each person ordered, then create an itemised bill based on each person actually ate</p>"},{"location":"simple-projects/split-the-bill/#spliting-the-bill-with-a-social-group","title":"Spliting the bill with a Social Group","text":"<p>Extend the exercise by splitting bills over multiple events and activities with multiple people.</p>"},{"location":"simple-projects/tripple-lock/","title":"Triple Lock","text":"<p>A new safe too keep all the richest you will gain from becoming a Clojure developer (hopefully).  The safe has a 3 combination lock to protect your new found wealth, but just how safe is the safe?</p>"},{"location":"simple-projects/tripple-lock/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/triple-lock\n</code></pre>"},{"location":"simple-projects/tripple-lock/#designing-the-combination-lock","title":"Designing the combination lock","text":"<p>Lets consider how we would create such a combination lock in Clojure.</p> <ul> <li>The combination is managed by three tumbler wheels</li> <li>Each tumbler wheel has the same range of numbers on then, 0 to 9</li> </ul> <p>Each tumbler wheel could have all the numbers it contains within a Collection in Clojure.  The simplest approach would be to put the numbers 0 to 9 into a Vector (an array-like collection).</p> <pre><code>[0 1 2 3 4 5 6 7 8 9]\n</code></pre> <p>As the numbers on the tumbler wheel are just a range between 0 and 9, then rather than type out all the numbers we can use the <code>range</code> function to generate all the numbers for us.</p> <p>When we give the range function one argument, it will create all the whole numbers from 0 to the number before that of the argument.  In the following example, we give <code>range</code> the argument of 10 and we receive the numbers from 0 to 9.</p> <pre><code>(range 10)\n</code></pre> <p>You can also give <code>range</code> two arguments, such as '(range 5 15)'.</p> <p>Be careful not to call the <code>range</code> function by itself, or it will try and generate an infinite range of numbers (until your computer memory is all used up).</p>"},{"location":"simple-projects/tripple-lock/#create-all-the-combinations","title":"Create all the Combinations","text":"<p>Complete the following code (replacing the ,,,) to generate all the possible combinations of the lock</p> <pre><code>(for [tumbler-1 (range 10)\n      ,,,     ,,,\n      ,,,     ,,,]\n [tumbler-1 ,,,   ,,,])\n</code></pre> <p>Instead of showing all the possible combinations, count all the combinations and return the total number of combinations</p> <p>Take the code from the combinations and wrap it in the count function</p> <pre><code>;; now count the possible combinations\n(count\n\n         )\n</code></pre> <p>To make our lock harder to break into, we should only allow the combinations where each tumbler wheel has a different number.  So you cannot have combinations like 1-1-1, 1-2-2, 1-2-1, etc.</p> <p>How many combinations does that give us?</p> <p>Complete the following code to create a 3-tumbler wheel combination lock, where none of the numbers are the same</p> <p>Hint: Beware not to enter (range) without an argument as Clojure may try and evaluate infinity</p> <pre><code>(count (for [tumbler-1 (range 10)\n             ,,,     ,,,\n             ,,,     ,,,\n             :when (or (= tumbler-1 tumbler-2)\n                       ,,,\n                       ,,,)]\n         [tumbler-1 ,,,   ,,,]))\n</code></pre> Suggested solution <p>Suggested solution to the completed 3-lock challenges. <pre><code>;; a 3 combination padlock\n\n;; model the combinations\n(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)]\n [tumbler-1 tumbler-2 tumbler-3])\n\n\n;; now count the possible combinations\n(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)]\n         [tumbler-1 tumbler-2 tumbler-3]))\n\n\n(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)\n             :when (or (= tumbler-1 tumbler-2)\n                       (= tumbler-2 tumbler-3)\n                       (= tumbler-3 tumbler-1))]\n         [tumbler-1 tumbler-2 tumbler-3]))\n\n;; lets look at the combinations again, we can see that there is always at least 2 matching values.  This is probably the opposite of what we want in real life.\n(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)\n      :when (or (= tumbler-1 tumbler-2)\n                (= tumbler-2 tumbler-3)\n                (= tumbler-3 tumbler-1))]\n  [tumbler-1 tumbler-2 tumbler-3])\n</code></pre></p>"},{"location":"simple-projects/data-transformation/","title":"Data Transformation","text":"<p>In a sense all Clojure project are about data transformation, however, these projects will introduce you to many techniques used to transform larger and larger data sets.</p> <p></p> Project Topics Overview Most common word regex filter re-seq sort-by Find the most common word in a give book that is not a common English word"},{"location":"simple-projects/data-transformation/most-common-word/","title":"Most common word","text":"<p>In this challenge we would like you to find the most used word in a book. The word should not be part of the common English words (i.e. the, a, i, is).</p> <p>This functionality is useful for generating word maps or identifying patterns across data sets.</p> <p></p> <p>Copyright free books for use are available via Project Guttenburg, e.g. \u201cThe Importance of Being Earnest\u201d by Oscar Wilde.</p>"},{"location":"simple-projects/data-transformation/most-common-word/#suggested-approach","title":"Suggested approach","text":"<p>A suggested approach to find the most common word:</p> <ul> <li>Pull the content of the book into a collection</li> <li>Use a regular expression to create a collection of individual words - eg. <code>#\u201d[a-zA-Z0-9|\u2019]+\u201d</code></li> <li>Remove the common English words used in the book</li> <li>Convert all the words to lower case so they match with common words source</li> <li>Count the occurrences of the remaining words (eg. each word is associated with the number of times it appears in the book)</li> <li>Sort the words by the number of the occurrences</li> <li>Reverse the collection so the most commonly used word is shown first</li> </ul>"},{"location":"simple-projects/data-transformation/most-common-word/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/common-words\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#get-the-book-contents","title":"Get the book contents","text":"<p><code>clojure.core/slurp</code> will read in a local file or a remote resource (file, web page, etc) and return a single string of the contents.</p> <pre><code>(slurp \"https://www.gutenberg.org/files/844/844-0.txt\")\n</code></pre> <p>Wrap the <code>slurp</code> expression in a <code>def</code> to bind a name to the book.</p> <pre><code>(def being-earnest (slurp \"https://www.gutenberg.org/files/844/844-0.txt\"))\n</code></pre> <p>Project Gutenberg now compresses the books with GZip, so a stream can be created to read the file and decompress it.  Then slurp is used to read in the uncompressed text of the book into a string.</p> <pre><code>(def being-earnest\n  (with-open [uncompress-text (java.util.zip.GZIPInputStream.\n                  (clojure.java.io/input-stream\n                   \"https://www.gutenberg.org/cache/epub/844/pg844.txt\"))]\n    (slurp uncompress-text)))\n ```\n\n## Individual words from the book\n\nThe book contents should be broken down into individual words.\n\nA regular expression can be used to identify word boundaries, especially where there are apostrophes and other characters.\n\n`clojure.core/re-seq` returns a new lazy sequence containing the successive matches of a pattern from a given string.  So given a sentence\n\nUsing `re-seq` to convert the first sentence of the `being-earnest` book using a regex word boundary pattern, `\\w+`.\n\n```clojure\n(re-seq #\"\\w+\" \"Morning-room in Algernon's flat in Half-Moon Street.\")\n\n;; =&gt; (\"Morning\" \"room\" \"in\" \"Algernon\" \"s\" \"flat\" \"in\" \"Half\" \"Moon\" \"Street\")\n</code></pre> <p>The result is a sequence of the individual words, however, the hyphenated words and the apostrophes have been split into separate words.</p> <p>Extending the regex pattern the results can be refined.</p> <pre><code>(re-seq #\"[\\w|'-]+\" \"Morning-room in Algernon's flat in Half-Moon Street.\")\n\n;; =&gt; (\"Morning-room in Algernon's flat in Half-Moon Street\")\n</code></pre> <pre><code>(re-seq #\"[\\w|'-]+\" being-earnest)\n</code></pre> <p>The #\"[\\w|'-]+\" is the same pattern as the more explicit pattern #\"[a-zA-Z0-9|'-]+\"</p>"},{"location":"simple-projects/data-transformation/most-common-word/#removing-common-english-words","title":"Removing common English words","text":"<p>In any book the most common word its highly likely to be a common English word (the, a, and, etc.).  To make the most common word in any book more specific, the common English words should be removed.</p> <p><code>common-english-words.csv</code> contains comma separate words.</p> <p>Using slurp and a regular expression the individual words can be extracted into a collection.</p> <p>Rather than <code>re-seq</code> the <code>clojure.string/split</code> can be used.  This is a more specific function for splitting a string using a regular expression pattern, in this case the pattern for a comma, <code>#\",\"</code>.</p> <pre><code> (clojure.string/split (slurp \"common-english-words.csv\") #\",\")\n</code></pre> <p>An additional step is to place the common English words into a Clojure set, a data structure which contains a unique set of values.</p> <pre><code> (set (clojure.string/split (slurp \"common-english-words.csv\") #\",\"))\n</code></pre> <p>The advantage of using a set for the common English words is that the data structure can be used as a predicate to remove matching words.  So a common English words set can be used to remove the common English words from <code>being-earnest</code> book.</p> <p>Define a name for the common English words set.</p> <pre><code>(def common-english-words (set (clojure.string/split (slurp \"common-english-words.csv\") #\",\")))\n</code></pre> <p>This can also be written using the threading macro, to show the sequential nature of the data transformation.</p> <pre><code>(def common-english-words\n  (-&gt; (slurp \"common-english-words.csv\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre> <p>The <code>common-english-words</code> set can now be used with the <code>being-earnest</code> book.</p> <pre><code>(remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#counting-occurrences","title":"Counting Occurrences","text":"<p><code>clojure.core/frequencies</code> takes a collection and returns a map where the keys are the unique elements from the collection and the value for each key is the number of times that element occurred in the collection.</p> <pre><code>(filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest)))\n</code></pre> <p>The resulting hash-map is not in any order.  <code>clojure.core/sort-by</code> will return the same results but sorted by a given function.  To sort a hash-map the <code>key</code> and <code>val</code> functions are function that will sort by key and value respectively.  As it is the value that has the number of occurrences, then <code>val</code> is the function to use.</p> <pre><code>(sort-by val (filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))))\n</code></pre> <p>The result is sorted from smallest to largest value.  The result could be reversed using <code>clojure.core/reverse</code> or by supplying an extra function to the <code>sort-by</code> expression.  Using greater-than, <code>&gt;</code> the result will be returned in descending order.</p> <pre><code>(sort-by val dec (filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))))\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#assembling-the-most-common-word-function","title":"Assembling the most-common-word function","text":"<p>Define a function called <code>most-common-word</code> that assembles all the previous steps.  The function should take all the values it needs for the calculation as arguments, creating a pure function without side effects.</p> <pre><code>(defn most-common-word\n  [book common-words]\n  (sort-by val &gt;\n    (frequencies\n      (remove common-words\n        (map #(clojure.string/lower-case %)\n             (re-seq #\"[\\w|'-]+\" book))))))\n</code></pre> <p>This may seem a little hard to parse, so the function definition can be re-written using a threading macro.</p> <pre><code>(defn most-common-word\n  [book common-words]\n  (-&gt;&gt; book\n       (re-seq #\"[\\w|'-]+\" ,,,)\n       (map #(clojure.string/lower-case %))\n       (remove common-words)\n       frequencies\n       (sort-by val &gt;)))\n</code></pre> <p>Call this function with the <code>being-earnest</code> book and the <code>common-english-words</code></p> <pre><code>(most-common-word being-earnest common-english-words)\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#running-from-the-command-line","title":"Running from the command line","text":"<p>Update the code to take the book reference from the command line.</p> <p>Remove the <code>def</code> that hard-coded the being-earnest book.</p> <p>In the <code>most-common-word</code> wrap the book with <code>slurp</code> to read the book reference in and convert it to a string, to be processed by the rest of the expressions.</p> <p>Add a <code>-main</code> function that takes a reference for the source of the book and the source of the common words.</p> <pre><code>(ns practicalli.common-word)\n\n(defn decode-book\n  [book-gzip]\n  (with-open\n    [uncompress-text (java.util.zip.GZIPInputStream.\n                      (clojure.java.io/input-stream book-gzip))]\n    (slurp uncompress-text)))\n\n(defn common-words\n  [csv]\n  (-&gt; (slurp csv)\n      (clojure.string/split #\",\")\n      set))\n\n(defn most-common-word\n  [book-gzip common-words]\n  (-&gt;&gt; (decode book-gzip)\n       (re-seq #\"[\\w|'-]+\")\n       (map #(clojure.string/lower-case %))\n       (remove common-words)\n       frequencies\n       (sort-by val &gt;)))\n\n(defn -main\n  [book-gzip common-word-csv]\n  (most-common-word book-gzip (common-words common-word-csv)))\n</code></pre> <p>Now call the code on the command line.</p> <pre><code>clojure -m practicalli.common-word \"https://www.gutenberg.org/cache/epub/844/pg844.txt\" \"common-english-words.csv\"\n</code></pre>"},{"location":"simple-projects/encode-decode/","title":"Encoding and Decoding with Clojure","text":"<p>Projects that use a range of ciphers, from simple to more complex, to encode and decode text.</p> <p>A common approach to encoding and decoding text is to use a dictionary lookup, defined in Clojure as a hash-map. Each key-value pair provides a mapping for encoding and decoding.  Looking up a a character as a key in the map provides a value that is the encrypted character.</p> <p>These projects show several ways to transform data in Clojure.</p> Project Topics Description Boolean names to 0 or 1 hash-map get Convert boolean values to classic 1 or 0 values Caesar cipher - ROT13 seq cycle zipmap A simple alphabet rotation cipher RNA / DNA converter Convert between DNA and RNA Clacks telegram Encoding and decoding messages with Clacks"},{"location":"simple-projects/encode-decode/#examples-of-encoding","title":"Examples of Encoding","text":"<ul> <li>Portable Network Graphics for image compression</li> <li>Vorbis for music and video compression plus several commercial compression encoders</li> <li>Enigma machine - encrypted communications</li> </ul>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/","title":"Caesar Cipher ROT13","text":"<p>ROT13 is one of the simplest ciphers which uses an alphabet as a circle of characters, swapping each character with a character 13 positions later in the alphabet, assuming 26 character of an English alphabet.</p> <p>A dictionary can be generated to translate between the original alphabet and the rotated alphabet, providing a simple way to generate an encrypted message.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/caesar-cipher\n</code></pre>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#define-an-alphabet","title":"Define an alphabet","text":"<p>Define an alphabet to use as a basis for conversion.  Take the string of all characters and convert to a sequence of character types.</p> src/practicalli/caesar-cipher.clj<pre><code>(def english-alphabet\n  (seq \"abcdefghijklmnopqrstuvwxyz\"))\n</code></pre>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#generate-a-cypher","title":"Generate a cypher","text":"<p>To convert a character, first build up a cypher.  A cypher in this case is simply a hash-map that creates a dictionary lookup defining what each character should be changed to.</p> <p><code>cycle</code> creates a lazy sequence of the alphabet that continually cycles.  This provides an 'infinite' sequence from which we will take only the characters needed.</p> <pre><code>(cycle \"abcdefghijklmnopqrstuvwxyz\")\n</code></pre> <p>The dictionary is composed of the original alphabet and a new alphabet that is offset by 13 characters, half the number of characters in the dictionary.</p> <p><code>(drop 13 (cycle alphabet))</code>  will drop the first 13 characters.  As <code>cycle</code> creates an 'infinite' alphabet, there are still plenty of characters to make a second alphabet.</p> <p><code>(take 26 (drop 13 (cycle alphabet)))</code> will get a new alphabet of 26 characters, starting from the 14th character, <code>n</code>.</p> <p><code>zipmap</code> is used to join two collections together to form a hash-map, e.g. the lookup dictionary. In this case the original alphabet and the new alphabet.</p> <p><code>(zipmap alphabet (take 26 (drop 13 (cycle alphabet))))</code></p> <p>This expression is nested and can be harder to parse by those new to Clojure.  The code can be written using a threading marco, that demonstrated the flow of data transformation.</p> <p>Using the thread last macro, <code>-&gt;&gt;</code>, the result of each expression becomes the last argument for the next expression.</p> <pre><code>(-&gt;&gt; (cycle alphabet)\n     (drop 13)\n     (take 26)\n     (zipmap alphabet))\n</code></pre> <p>Using the clojure.core/replace function with the cypher hash-map and a string of text returns a converted string of text.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#define-a-function","title":"Define a function","text":"<p>Define a <code>rot13</code> function with the algorithm created.  The function takes the alphabet and the text to be encrypted.  Passing both pieces of data as arguments ensures that the function is pure, i.e. free from side effects.</p> src/practicalli/caesar-cipher.clj<pre><code>(defn rot13 [alphabet text]\n  (let [cipher (-&gt;&gt; (cycle alphabet)\n                    (drop 13)\n                    (take 26)\n                    (zipmap alphabet))]\n    (apply str (replace cipher text))))\n</code></pre> <p>Call the rot13 function with the <code>english-alphabet</code> and a sentence as a string.</p> <pre><code>(rot13 english-alphabet \"The Quick Brown Fox Jumped Over The Lazy Dog!\")\n</code></pre> <p>An encrypted copy of the sentence is returned.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#idiomatic-improvements","title":"Idiomatic improvements","text":"<p><code>clojure.string</code> library is more idiomatic approach when working with string types.</p> <p>In the <code>practicalli.cypher-rot13</code> solution <code>apply str</code> was used to join a sequence of characters into a string.  <code>clojure.string/join</code> combines a sequence of characters into a string.</p> <p>Require the <code>clojure.string</code> namespace to use the functions contained within.  Add the require to the namespace definition of <code>practicalli.cypher-rot13</code></p> src/practicalli/caesar-cipher.clj<pre><code>(ns practicalli.ceaser-cypher\n  (:gen-class)\n  (:require [clojure.string :as string]))\n</code></pre> <p>Update the <code>rot13</code> function to use <code>clojure.string/join</code> rather than <code>apply str</code>.</p> <pre><code>(defn rot13 [alphabet text]\n  (let [cipher (-&gt;&gt; (cycle alphabet)\n                    (drop 13)\n                    (take 26)\n                    (zipmap alphabet))]\n    (string/join (replace cipher text))))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/","title":"Clacks Messages","text":"<p>In the 33rd Discworld novel, Going Postal, messages are sent faster than a speeding horse via the Clacks system.  The Clacks system composes of a series of towers spread across a continent with each tower sending a light signal to the next tower using combinations of lights for each character in the message.  Each tower sees a grid of lights from a distant tower and sends the message on to the next tower.</p> <p>The Clacks system was introduced in the 24th Discworld novel called \"The Fifth Elephant\". \"Going Postal\" elaborates the full history of the Clacks system.</p>"},{"location":"simple-projects/encode-decode/clacks/#the-challenge","title":"The Challenge","text":"<p>Create a Clacks encoder that converts any English language message into its corresponding clacks signal, based on the Clacks alphabet as defined by the board game of the same name.</p> <p>The board game defines the alphabet as a 2 by 3 grid (although in the Discworld its actually 8 large squares).  Naturally, the interpreter also converts the Clacks signal back into an English message too.</p> <p></p>"},{"location":"simple-projects/encode-decode/clacks/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/clacks-messenger\n</code></pre> <p>This project has a <code>deps.edn</code> file that includes the aliases</p> <ul> <li><code>:test</code> - includes the <code>test/</code> directory in the class path so unit test code is found</li> <li><code>:runner</code> to run the Cognitect Labs test runner which will find and run all unit tests</li> </ul>"},{"location":"simple-projects/encode-decode/clacks/#representing-a-clack","title":"Representing a Clack","text":"<p>For each clack, the light pattern is read from the top of the first column to the bottom, then from the top of the second column to the bottom.  A light in a position represents a 1 value and no light represents a 0 value.  This gives us our 6 number pattern for each clack in the alphabet.</p> <p>The initial data structure chosen was essentially just modelling each individual clack.  Since a clack is a 2x3 structure, the simplest way to represent a clacks is to have a vector that contains 2 vectors, each with three elements.</p> <p>So a simple expression of the letter a in the clacks alphabet would be:</p> <pre><code>[[0 1 0][0 0 1]]\n</code></pre> <p>Therefore we could define a single letter of our alphabet as follows:</p> <pre><code>(def a [[0 1 0][0 0 1]])\n</code></pre> <p>Before defining the complete alphabet using this data structure, test this is the right data structure for the conversion process.</p>"},{"location":"simple-projects/encode-decode/clacks/#test-simple-conversion","title":"Test simple conversion","text":"<p>Define a function to convert a single character into a clack:</p> <pre><code>(defn character-&gt;clack [character]\n  (if (= character \"a\")\n    a\n    (str \"Sorry, character is not yet in the alphabet, please create a pull request\")))\n</code></pre> <p>Calling the function converts a string into the corresponding clack</p> <pre><code>(character-&gt;clack \"a\")\n</code></pre> <p>Clojure function naming</p> <p><code>-&gt;</code> is a naming convention to indicate a function is specifically transforming to a data format.  For example, <code>json-&gt;clj-map</code> would be a generic function for transforming json to Clojure hash-map</p> <p>The code is simple for a single character, however, would require a lot of redundant code to convert the whole alphabet.  We would need either a deeply nested set of if statements or a very long <code>cond</code> function, neither of which seems to be a particularly functional approach or idiomatic Clojure.</p> <p>If a <code>cond</code> statement was used, how would a clacks be converted back into a character?</p> <p>So perhaps we need to change the data structure, one that provides an easy way to map to values together.</p> <p>Also, there seems no value in mapping values to a 2x3 grid as long as we consistently express a clack.</p>"},{"location":"simple-projects/encode-decode/clacks/#define-the-alphabet","title":"Define the alphabet","text":"<p>A hash map associates each key with a value and are used to create self-describing data. For example a person could be described as a hash-map</p> <pre><code>{:name \"Jenny Jetpack\" :age \"21\" :twitter \"jenjetpack\"}\n</code></pre> <p>Clojure keywords are often used for the keys because keywords can be used as a function with a map as an argument.  This will return the value associated with the keyword in the map.</p> <p>The new design for the clacks data structure associates a keyword of each letter of the alphabet with its corresponding clacks light pattern code</p> <pre><code>{:a [0 1 0 0 0 1]}\n</code></pre> <p>Test the design by defining enough letters for the clacks alphabet to convert some simple words, i.e bat</p> <pre><code>(def alphabet {:a [0 1 0 0 0 1]\n               :b [0 0 1 0 1 0]\n               :t [1 0 0 1 1 1]})\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#testing-the-map-design","title":"Testing the map design","text":"<p>Use a keyword to lookup the value of its clack code</p> <pre><code>(:a alphabet)\n\n;; =&gt; [0 1 0 0 0 1]\n</code></pre> <p>Create a simple function to convert a single character to its Clacks representation, referred to a clack.</p> <pre><code>(defn character-&gt;clack [character]\n    ((keyword character) alphabet))\n</code></pre> <p>The <code>-&gt;</code> character is part of the function name.  This is a Clojure naming convention used when the function you are defining converts from one type to another.</p> <p>And call the function as follows</p> <pre><code>(character-&gt;clack \"a\")\n\n;; =&gt; [0 1 0 0 0 1]\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#converting-a-word","title":"Converting a word","text":"<p>Now we want to convert a whole word to a clacks sequence.  It seemed the easiest way to convert a whole word was to convert each letter at a time using the map to look up each clack code, returning all the clacks codes in a sequence.</p> <p>So we redefined the <code>string-&gt;clacks</code> function to take in a whole word.</p> <p>We used the <code>map</code> function to apply a conversion function over each element in the word (each element of the string).  This conversion function called <code>clacksify</code>.</p> <pre><code>(defn clacksify [letter]\n  (let [character (str letter)]\n  (alphabet (keyword character))))\n\n(defn string-&gt;clacks [word]\n  (map clacksify word))\n</code></pre> <p>Now we could convert any word that used the letters of our limited alphabet.  We chose bat as a simple word.</p> <pre><code>(string-&gt;clacks \"bat\")\n</code></pre> <p>As we are passing a string and not a keyword to the <code>clacksify</code> function, then we first convert the string to a keyword using the <code>keyword</code> function.</p>"},{"location":"simple-projects/encode-decode/clacks/#converting-the-clack-to-a-string","title":"Converting the clack to a string","text":"<p>Is there a simple way to look up a key given a value that is unique in the map?</p> <p>All Clack codes are unique in the map, but there did not seem to be a simple expression to find the key when given a value.</p> <p>We could have created a second mapping, however having two maps seemed redundant and a potential cause for silly bugs.</p> <p>The answer was simple once we found it.  As the clack codes are unique, they could be used as keys for the letter values, we just needed to swap the map around.  Swapping a map's keys and values was done by writing a <code>reverse-map</code> function.</p> <pre><code>(defn reverse-map\n  \"Reverse the keys and value pairs in a map.\n  Allows the map to be used to convert from a clack to a letter without defining a second map\"\n  [m]\n  (into {} (map (fn [[a b]] [b a]) m)))\n</code></pre> <p>So we defined the function <code>declacksify</code> which takes a clack code and returns its corresponding character.  The clack code returns the corresponding keyword rather than a character, so we use the <code>name</code> function to convert the keyword into a character name.</p> <pre><code>(defn declacksify [clack]\n  (name ((reverse-map alphabet) clack)))\n\n(defn clacks-&gt;string [clacks]\n  (map declacksify clacks))\n</code></pre> <p>So calling these functions with a clacks</p> <pre><code>(declacksify  [1 0 0 1 1 1])\n;; =&gt; \"t\"\n\n(clacks-&gt;string [[0 0 1 0 1 0] [0 1 0 0 0 1] [1 0 0 1 1 1]])\n;; =&gt; (\"b\" \"a\" \"t\")\n</code></pre> <p>At this point you may be thinking that using keywords to represent the characters of the alphabet may not be the most effective.  Using keywords has required more code to be written, adding to the complexity of the solution.</p>"},{"location":"simple-projects/encode-decode/clacks/#tidy-output","title":"Tidy output","text":"<p><code>clacks-&gt;string</code> function returns the right result, but not quite in the format required.  Rather than a single string a sequence of characters is returned.</p> <p>Using the <code>map</code> function we can apply the <code>str</code> function over the resulting characters to give a single string.</p> <pre><code>(defn clacks-&gt;string [clacks]\n(map str (map declacksify clacks)))\n</code></pre> <p>Using <code>clojure.string/join</code> is a more idiomatic approach to converting a sequence of characters to a string</p> <pre><code>(require '[clojure.string :as string])\n\n(defn clacks-&gt;string [clacks]\n  (string/join (map declacksify clacks)))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#refactor-dictionary-design","title":"Refactor dictionary design","text":"<p>Converting characters to keywords and back again seem redundant when characters themselves can be used as keys in a hash-map.</p> <p>Using keywords is problematic when it comes to the space character as a keyword cannot be a space.  Using <code>:-</code> to represent a space required the clacksification and declacksification functions to convert between <code>:-</code> and the space character.  This also prevents hyphenated words working in the Clacks system.</p> <p>Refactor the dictionary to use a string for each character as the keys in the map, instead of Clojure keywords.  This solves the issue with space and other special characters.</p> <pre><code>(def dictionary\n  {\"a\"  [0 1 1 0 0 0 0 1]\n   \"b\"  [0 1 1 0 0 0 1 0]\n   \"c\"  [0 1 1 0 0 0 1 1]\n   \"d\"  [0 1 1 0 0 1 0 0]\n   \"e\"  [0 1 1 0 0 1 0 1]\n   ,,,})\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#refactor-namespace","title":"Refactor namespace","text":"<p>As the dictionary can be quite large to represent in code, move the dictionary definition to its own namespace.</p> <p>Use a more specific name for the dictionary, describing what languages the dictionary is used for</p> <pre><code>(def english-&gt;clacks\n  {\"a\"  [0 1 1 0 0 0 0 1]\n   \"b\"  [0 1 1 0 0 0 1 0]\n   \"c\"  [0 1 1 0 0 0 1 1]\n   \"d\"  [0 1 1 0 0 1 0 0]\n   \"e\"  [0 1 1 0 0 1 0 1]\n   ,,,})\n</code></pre> <p>A dictionary is required to translate from Clacks to English to decode the messages. Rather than write the reverse mappings for each character in the dictionary, in effect creating a second directory for the same two languages, use a function to invert the map by swapping keys and values.</p> <p><code>clojure.set/map-invert</code> will swap each key/value pair in the map so the key becomes the value and the value becomes the key.</p> <p>Define a <code>clacks-&gt;english</code> dictionary that holds the result of the <code>map-invert</code> function call</p> <pre><code>(ns practicalli.clacks-dictionary\n  (:require [clojure.set]))\n\n(def clacks-&gt;english { ,,, })\n\n(def clacks-&gt;english (clojure.set/map-invert english-&gt;clacks))\n</code></pre> <p>Require the dictionary namespace using the alias <code>dictionary</code> to give the dictionary names context when used in the main namespace.</p> <p>Also require <code>clojure.string</code> using the alias <code>string</code> to use the join function.</p> <pre><code>(ns practicalli.clacks-messenger\n  (:require [practicalli.clacks-dictionary :as dictionary]\n            [clojure.string :as string]))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#removing-side-effects","title":"Removing side effects","text":"<p>Designing pure functions, those that receive all their data via arguments, is a common way to remove side effects.</p> <p>Include the dictionary as an argument to each of the functions.  This ensures that each function is pure and prevents side effects (side causes).</p> <pre><code>(defn character-&gt;clack [char dictionary]\n  (let [character (str char)]\n    (get dictionary character)))\n\n(defn message-&gt;clacks [message dictionary]\n  (map #(character-&gt;clack % dictionary) message))\n\n(defn clack-&gt;character [clack dictionary]\n  (get (clojure.set/map-invert dictionary) clack))\n\n(defn clack-&gt;character [clack dictionary]\n  (get dictionary-inverted clack))\n\n;; Create a clacks code back to a message\n\n(defn clacks-&gt;message [clacks dictionary]\n  (string/join (map #(clack-&gt;character % dictionary) clacks)))\n</code></pre> <p>Test the updated functions by calling them via the REPL</p> <pre><code>(message-&gt;clacks \"cab\" dictionary/english-&gt;clacks)\n;; =&gt; ([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0])\n\n(message-&gt;clacks \"cab cab\" dictionary/english-&gt;clacks)\n;; =&gt; ([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0] [0 0 0 0 0 0 0 0] [0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0])\n\n;; Create a character from a clack code\n\n;; test data\n(clacks-&gt;message '([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0]) dictionary/english-&gt;clacks)\n\n(clacks-&gt;message\n '([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0] [0 0 0 0 0 0 0 0] [0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0]) dictionary)\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#use-alternative-dictionaries","title":"Use alternative dictionaries","text":"<p>Thanks to a flexible design with no side effects or side causes then its really easy to replace the English language alphabet with another language that can be encoded into Clack codes.</p> <p>All that is required is to define a dictionary for another language.  So languages based on the greek, latin or cyrillic alphabet could be send if a suitable alphabet with clack codes is supplied.</p>"},{"location":"simple-projects/encode-decode/convert-boolean-values/","title":"Convert boolean values","text":""},{"location":"simple-projects/encode-decode/convert-boolean-values/#convert-boolean-true-false-to-1-and-0","title":"Convert boolean true false to 1 and 0","text":"<p>A very simple example of encoding and decoding is converting the Clojure values of <code>true</code> and <code>false</code> to <code>1</code> and <code>0</code> respectively.</p> <p>Using <code>1</code> for true and <code>0</code> for false has been a common idiom in programming languages, especially where a language did not include <code>true</code> and <code>false</code> syntax.</p>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#define-an-association-between-values","title":"Define an association between values","text":"<p>Define a Clojure <code>hash-map</code> to associate the Clojure boolean <code>true</code> an <code>false</code> values to <code>1</code> and <code>0</code> respectively</p> <pre><code>{false 0\n true 1}\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#find-an-associated-value-for-the-conversion","title":"Find an associated value for the conversion","text":"<p>Using the <code>get</code> function the <code>boolean-value</code> is used to find a matching key in the map and if found the value that key is associated is returned.</p> <pre><code>(get {false 0 true 1} boolean-value)\n</code></pre> <p>Example:</p> <pre><code>(get {false 0 true 1} true)\n</code></pre> <p>A map can be called, just like a function.  the <code>boolean-value</code> is passed to the map as a function argument. As with the <code>get</code> expression, if the map contains the key the associated value is returned.</p> <pre><code>({false 0 true 1} boolean-value)\n</code></pre> <p>Example:</p> <pre><code>({false 0 true 1} true)\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#convert-multiple-boolean-values","title":"Convert multiple boolean values","text":"<p>If there are a collection of boolean values to convert, the <code>map</code> function can be used to convert them all to 1 or 0.</p> <p>Map this over a collection of values</p> <pre><code>(map {false 0 true 1} [collection-of-boolean-values])\n</code></pre> <p>Example:</p> <pre><code>(map {false 0 true 1} [true false false true true true false false true false true false false true])\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#how-does-this-work","title":"How does this work?","text":"<p>The <code>map</code> function takes two arguments, a function and a collection.  The <code>map</code> function calls the function given as an argument and calls it with each element of the collection in turn.  The result of each call is remembered by the <code>map</code> function and when the last element of the collection has been used, a new collection of all the results is returned.</p> <p>In the above example, the hash-map {false 0 true 1} acts as a function.</p> <pre><code>({false 0 true 1} true)\n</code></pre> <p>A hash-map acts as a function in that it can return an associated value when given a key as an argument.</p> <p>Calling <code>{false 0 true 1}</code> with <code>true</code> as an argument returns the value <code>1</code>.</p>"},{"location":"simple-projects/encode-decode/rna-dna/","title":"RNA to DNA transcription","text":"<p>Given a DNA strand, return its RNA complement (RNA transcription).</p> <p></p> <p>Both DNA and RNA strands are a sequence of nucleotides.</p> <p>The four nucleotides found in DNA are adenine (A), cytosine (C), guanine (G) and thymine (T).</p> <p>The four nucleotides found in RNA are adenine (A), cytosine (C), guanine (G) and uracil (U).</p> <p>Given a DNA strand, its transcribed RNA strand is formed by replacing each nucleotide with its complement:</p> <pre><code>G -&gt; C\nC -&gt; G\nT -&gt; A\nA -&gt; U\n</code></pre> Inspired by Exercism.io challenge <p>This project was inspired by the RNA Transcription exercise on Exercism.io.  Related exercises include Nucleotide Count and Hamming.</p>"},{"location":"simple-projects/encode-decode/rna-dna/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/rna-transcription\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#define-unit-tests","title":"Define unit tests","text":"<p>Open the <code>test/practicalli/rna-transcription.clj</code> and add the following tests</p> <pre><code>(ns practicalli.rna-transcription-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [rna-transcription :as SUT]))\n\n(deftest rna-transcription-test\n  (testing \"transcribe cytosine to guanine\"\n    (is (= \"G\" (SUT/to-rna \"C\"))))\n\n  (testing \"transcribe guanine to cytosine\"\n    (is (= \"C\" (SUT/to-rna \"G\"))))\n\n  (testing \"transcribe adenine to uracil\"\n    (is (= \"U\" (SUT/to-rna \"A\"))))\n\n  (testing \"transcribe thymine to adenine\"\n    (is (= \"A\" (SUT/to-rna \"T\"))))\n\n  (testing \"transcribe all nucleotides\"\n    (is (= \"UGCACCAGAAUU\" (rna-transcription/to-rna \"ACGTGGTCTTAA\"))))\n\n  (testing \"validate dna strands\"\n    (is (thrown? AssertionError (rna-transcription/to-rna \"XCGFGGTDTTAA\")))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#code-the-rna-transcription","title":"Code the RNA transcription","text":"<p>Edit the <code>src/practicalli/rna-transcription.clj</code> file and require the <code>clojure.string</code> library.  The library is part of the Clojure standard library, so does not need to be added as a project dependency.</p> <pre><code>(ns practicalli.rna-transcription\n  (:require [clojure.string :as string]))\n</code></pre> <p>Define a dictionary to convert from DNA nucleotide to its RNA complement</p> <pre><code>(def dictionary-dna-&gt;rna\n  \"Convert DNA to RNA\"\n  {\"G\" \"C\"\n   \"C\" \"G\"\n   \"T\" \"A\"\n   \"A\" \"U\"}\n  )\n</code></pre> <p>Define a function to convert a single DNA nucleotide (one of <code>G</code>, C, T, A) into its RNA complement, using the dictionary.</p> <p>The algorithm is a simple hash-map lookup using the DNA nucleotide as the Key and returning the RNA complement as the value.</p> <pre><code>(defn convert-nucleotide\n  \"Convert a specific nucleotide from a DNA strand,\n  into a nucleotide for an RNA strand\"\n  [dictionary nucleotide]\n  (get dictionary (str nucleotide)))\n</code></pre> <p>Now a single nucleotide can be converted, another function can be defined to convert all DNA nucleotides in a given sequence.</p> <pre><code>(defn to-rna [dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (apply str\n           (map #(convert-nucleotide dictionary-dna-rna %) dna))))\n</code></pre> <p>Although <code>apply str</code> provides the correct answer, it is more idiomatic to use the <code>clojure.string/join</code> function.</p> <pre><code>(defn to-rna [dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (string/join\n           (map #(convert-nucleotide dictionary-dna-rna %) dna))))\n</code></pre> <p>The functions provide the correct answer, however, <code>to-rna</code> is not a pure function as the dictionary is pulled in as a side cause.</p> <p>Update all the tests in <code>test/practicalli/rna-transcription.clj</code> to call <code>SUT/to-rna</code> with a dictionary included in the argument.</p> <pre><code>(ns practicalli.rna-transcription-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [rna-transcription :as SUT]))\n\n(deftest rna-transcription-test\n  (testing \"transcribe cytosine to guanine\"\n    (is (= \"G\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"C\"))))\n\n  (testing \"transcribe guanine to cytosine\"\n    (is (= \"C\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"G\"))))\n\n  (testing \"transcribe adenine to uracil\"\n    (is (= \"U\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"A\"))))\n\n  (testing \"transcribe thymine to adenine\"\n    (is (= \"A\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"T\"))))\n\n  (testing \"transcribe all nucleotides\"\n    (is (= \"UGCACCAGAAUU\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"ACGTGGTCTTAA\"))))\n\n  (testing \"validate dna strands\"\n    (is (thrown?\n           AssertionError\n           (SUT/to-rna SUT/dictionary-dna-&gt;rna \"XCGFGGTDTTAA\")))))\n</code></pre> <p>Update <code>to-rna</code> to be a pure function by including the dictionary as an argument and also pass the updated tests.</p> <pre><code>(defn to-rna [dictionary dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (string/join\n           (map #(convert-nucleotide dictionary %) dna))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#idiomatic-improvements","title":"Idiomatic improvements","text":"<p>The <code>to-rna</code> function is not pure, as it relies on a shared value in the namespace, the <code>dictionary-dna-rna</code> transcription map.</p> <p>Passing <code>dictionary-dna-rna</code> as an argument to the <code>to-rna</code> function as well as the dna sequence would make <code>to-rna</code> a pure function.  It would also allow use of a range of transcription maps.</p> <pre><code>(defn to-rna\n  \"Transcribe each nucleotide from a DNA strand into its RNA complement\n  Arguments: string representing DNA strand\n  Return: string representing RNA strand\"\n  [transcription dna]\n  (string/join\n    (map #(or (transcription %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre> <p>The change to the <code>to-rna</code> function will break all the tests.</p> <p>Updated unit tests that call <code>to-rna</code> with both arguments</p> <pre><code>(ns rna-transcription-pure-test\n  (:require [clojure.test :refer [deftest is]]\n            [rna-transcription-pure :as SUT]\n            [rna-transcription :as data]))\n\n(deftest transcribes-cytosine-to-guanine\n  (is (= \"G\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"C\"))))\n\n(deftest transcribes-guanine-to-cytosine\n  (is (= \"C\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"G\"))))\n\n(deftest transcribes-adenine-to-uracil\n  (is (= \"U\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"A\"))))\n\n(deftest it-transcribes-thymine-to-adenine\n  (is (= \"A\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"T\"))))\n\n(deftest it-transcribes-all-nucleotides\n  (is (= \"UGCACCAGAAUU\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"ACGTGGTCTTAA\"))))\n\n(deftest it-validates-dna-strands\n  (is (thrown? AssertionError (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"XCGFGGTDTTAA\"))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#hintexercisim-project-and-the-pure-function","title":"Hint::Exercisim project and the pure function","text":"<p>If you wish to keep the Exercisim project passing, then add a new namespace to the project by create a new file called <code>rna-transcript-pure.clj</code>.  Add the new design of the <code>to-rna</code> function to that namespace.  Copy the tests into a new namespace by creating a file called <code>rna-transcription-pure.clj</code> and update the tests to use two arguments when calling <code>to-rna</code></p>"},{"location":"simple-projects/encode-decode/rna-dna/#summary","title":"Summary","text":"<p>This exercise has covered the concept of using a Clojure hash-map structure as a dictionary lookup.</p>"},{"location":"simple-projects/mutating-state/","title":"Mutating State in a Controlled way","text":"<p>Mutating state should be used carefully and sparingly in Clojure (and all other programming languages).</p> <p><code>atom</code> is a mutable container that can manage any value. The atom ensures that only one call at a time can affect the value it manages.  This is part of the software transactions memory system in Clojure.</p> <p>As the atom is mutable in that the value it manages can be changed, however, this must be done with special commands (swap!, reset!, compare-and-set!, swap-vals!).</p> <p>Even though the atom is mutable, the values it manages are not.  They are normal immutable (unchangeable) Clojure values.</p> <p><code>ref</code> is similar to <code>atom</code> and can manage transactions, ensuring that all changes happen or no changes happen.</p> Project Topics Overview Mutants assemble atom swap! reset! Using an atom to manage state changes Undo/Redo atom add-watch Traversing the history of an atom Poker game atom swap! reset! ref Simple transaction management using atom and ref in a card game, using constraints on an atom"},{"location":"simple-projects/mutating-state/#references","title":"References","text":"<ul> <li>Atoms - clojure.org</li> <li>Refs and Transactions - clojure.org</li> <li>Agents - clojure.org</li> </ul>"},{"location":"simple-projects/mutating-state/mutants-assemble/","title":"Mutants Assemble","text":"<p>In this section you will apply changes to values, how to define your own simple functions.</p> <p>We will also introduce the following functions for the first time:</p> function Description <code>atom</code> create an anonymous function, one without a name <code>deref</code>, <code>@</code> assign a name to a function"},{"location":"simple-projects/mutating-state/mutants-assemble/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/mutants-assemble\n</code></pre> <p>Open the <code>src/practicalli/mutants_assemble.clj</code> file in a Clojure aware editor and start the REPL.</p>"},{"location":"simple-projects/mutating-state/mutants-assemble/#define-an-atom","title":"Define an atom","text":"<p>Use the <code>def</code> function to bind a name to an atom.</p> <p>The atom wraps data, initially an empty vector.</p> <pre><code>(def mutants (atom []))\n</code></pre> <p>The vector remains an immutable value, even though it is contained within a mutable atom container</p> <p>Define a function using <code>defn</code> which takes a mutant as an argument and updates the value managed by the atom.  The reference to the atom is also an argument, making this a pure function and more generic as any given atom can be updated with this function.</p> <pre><code>(defn add-mutant [mutants mutant]\n  (swap! mutants conj mutant))\n</code></pre> <p><code>swap!</code> uses a function to create a new value for the atom to manage.  In this case the <code>conj</code> function is used to join the value of mutant with the existing mutants atom value, creating a new vector.</p> <p><code>swap!</code> is a macro so the syntax is a little different. Essentially this is the same as an expression <code>(conj mutants mutant)</code>, with the value this returns swapped into the atom.</p> <p>Call the function with the <code>mutants</code> atom and a mutant to add, which is a string containing the name of a mutant character.</p> <pre><code>(add-mutant mutants \"Black Widow\")\n</code></pre> <p>The value the atom is managing has been swapped for a new value.  The original value was not modified (vectors are immutable) so the atom now points to a new value, a vector containing a string.</p>"},{"location":"simple-projects/mutating-state/mutants-assemble/#viewing-the-value-managed-by-the-atom","title":"Viewing the value managed by the atom","text":"<p>Use the <code>deref</code> function to see the value the atom is managing.</p> <pre><code>(deref mutants)\n</code></pre> <p>It is idiomatic to use <code>@</code> which is a syntax alias for the <code>deref</code> function, rather than explicitly using <code>deref</code>.</p> <pre><code>@mutants\n</code></pre>"},{"location":"simple-projects/mutating-state/mutants-assemble/#reset-the-atom-value","title":"Reset the atom value","text":"<p><code>reset!</code> will change the value managed by the atom by providing the new value.  This is simpler than using <code>swap!</code> as it does not use the existing value in the atom.</p> <pre><code>(reset! mutants [])\n</code></pre> <p>Now all the mutants are gone (and we can start looking for new ones to add).</p>"},{"location":"simple-projects/tdd-kata/","title":"Kata challenges","text":"<p>A kata is a small challenge that you attempt to solve in different ways, so experiment with your solutions to these challenges.</p> <p>Kata are often coupled with Test Driven Development approach.</p> Project Topics Overview Recent song-list TDD Keep a list of recent songs played, without duplicates Salary Slip Generator TDD Generate play slips for an employee <p>Code Kata Website</p> <p></p>"},{"location":"simple-projects/tdd-kata/recent-song-list/","title":"TDD Kata Recent Song-list","text":"<p>Create a recent song list to hold a unique set of songs that have been played.</p> <p>The most recently played song is at the start of the list, the least recently played song is the last in the list.</p> <ul> <li>A recently-used-list is initially empty.</li> <li>Songs in the list are unique, so repeatedly played songs should only appear once in the list</li> <li>Songs can be looked up by index, which counts from zero.</li> <li>The song list can be transitory (starting from empty each time) or persistent within a REPL session (examples use a transitory approach)</li> </ul> <p>Optional extras:</p> <ul> <li>Empty song names are not allowed.</li> <li>Add a limit to the number of songs the list contains, with the least recently added items dropped when that limit is reached.</li> </ul>"},{"location":"simple-projects/tdd-kata/recent-song-list/#create-project","title":"Create Project","text":"<p>Create a new project using clj-new</p> <pre><code>clojure -T:project/create practicalli/song-list\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#run-repl","title":"Run REPL","text":"<p>Start a Clojure REPL via a Clojure editor or via the command line from the root of the project directory</p> <p>Start rich terminal UI Clojure REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#unit-tests","title":"Unit Tests","text":"<p><code>clojure.test</code> library is part of Clojure standard library and is the most common way to write unit tests in Clojure</p> <p>Open <code>test/playground/song_list_test.clj</code> file in your editor and update the namespace definition to include <code>clojure.test</code></p> <p>Require clojure.test namespace</p> test/playground/song_list_test.clj<pre><code>(ns practicalli.song-list-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [playground.song-list :as song-list]))\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#run-tests","title":"Run Tests","text":"<p>Evaluate the <code>practicalli.song-list</code> and <code>practicalli.song-list-test</code> namespaces to load their code into the REPL</p> <p>Call the <code>run-tests</code> function in the REPL to get a report back on all of the tests in our current namespace (<code>song-list</code>)</p> Kaocha test runnerclojure.test runner <p> Practicall Clojure CLI Config provides the <code>:test/run</code> alias to run the Kaocha test runner.</p> <p>Kaocha test runner</p> <p>Open a command line in the root directory of the project and run the following command. <pre><code>clojure -X:test/run\n</code></pre></p> <p>Kaocha runs all the tests, stopping should a test fail.</p> <p>Kaocha test runner with file watch</p> <p>Use the <code>:test/watch</code> alias to automatically run tests when ever a file is saved <pre><code>clojure -X:test/run\n</code></pre></p> <p>Evaluate the project code and evaluate the <code>run-tests</code> function from <code>clojure.test</code> from within the REPL</p> <p>clojure.test runner</p> <pre><code>(run-tests)\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-list-exists","title":"Test song-list exists","text":"<p>Write a test to see if a recent song list exists.</p> <p>This is an opportunity to think about what kind of data structure you want to use to hold your recent song list.</p> <p>Try write the code first and then check that code with the examples provided (click to expand each code example box)</p> Test song-list exists <p>A simple test that checks for a <code>recent-songs</code> list src/playground/song_list.clj<pre><code>(deftest song-list-exists-test\n  (testing \"Does a recent song list exist\"\n    (is (vector? song-list/recent-songs))))\n</code></pre> <code>recent-songs</code> should be defined in <code>src/playground/recent-song-list.clj</code> before running the test, otherwise a compilation error will be returned.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#define-a-recent-song-list","title":"Define a recent song list","text":"<p>Edit <code>src/playground/song_list.clj</code> and define a name for the collection of recent songs</p> <p>Use an empty collection to start with.  Which collection type will you use though (hash-map <code>{}</code>, list <code>()</code>, set <code>#{}</code>, vector <code>[]</code>)?</p> recent-songs collection <p>Define a recent-song name for an empty vector src/playground/song_list.clj<pre><code>(def recent-songs [])\n</code></pre></p> Test First Approach <p>For a strict test first approach, a <code>recent-songs</code> name (symbol) would be defined that returns <code>false</code> or a falsy value, e.g. <code>nil</code></p> <p>A name (symbol) must be defined for use in the test so that the Clojure code can compile</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-list-is-empty","title":"Test song-list is empty","text":"<p>The recent song list should be empty to start with.</p> Check song list is empty <p>A simple test that compares an empty vector with the value of <code>recent-songs</code> src/playground/song_list.clj<pre><code>(deftest song-list-empty-test\n  (testing \"Is song list empty if we haven't added any songs\"\n    (is\n     (= [] song-list/recent-songs))))\n</code></pre></p> <p>Here is the same test using the <code>empty?</code> function instead of the <code>=</code> function.</p> <p>src/playground/song_list.clj<pre><code>(deftest song-list-empty-test\n  (testing \"Is song list empty if we haven't added any songs\"\n    (is\n     (empty? song-list/recent-songs))))\n</code></pre> Either of these tests could replace the test that the song list exists, as these tests would fail if the song list did not exist.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-adding-a-song-to-the-list","title":"Test adding a song to the list","text":"<p>Add a song to the collection, for example <code>Tubular Bells - Mike Oldfield</code></p> Test adding a song to the list test/playground/song_list_test.clj<pre><code>(deftest add-songs-test\n\n  (testing \"add song returns a song list with entries\"\n    (is\n     (not (empty?\n           (add-song \"Barry Manilow - Love on the rocks\" song-list/recent-songs)))))\n\n  (testing \"add multiple song returns a song list with entries\"\n    (is\n     (not (empty?\n           (-&gt;&gt; song-list/recent-songs\n             (add-song \"Mike Oldfield - Tubular Bells Part 1\")\n             (add-song \"Barry Manilow - Love on the rocks\")\n             (add-song \"Phil Colins - Sususudio\" )))))))\n</code></pre> <p>Other songs are avialbe and Practicalli makes no recommendation as to what songs should be used or listened too.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#function-to-add-song","title":"Function to add song","text":"<p>Create a function to add a song to the start of the song list.</p> Function to add song to list <p>The <code>add-song</code> function takes the name of a song and the song list to which it will be added.</p> <p>A Thread-last macro <code>-&gt;&gt;</code> is used to pass the song list over two functions.</p> <p>The <code>song-list</code> is first passed to the <code>remove</code> expression as its last argument.  This expression will remove any occurrence of the new song we want to add from the <code>song-list</code>.</p> <p>The results of the <code>remove</code> expression are then passed to the <code>cons</code> expression as its last argument.  The <code>cons</code> expression simply adds the new song to the start of the list, making it the most recent song.</p> src/playground/song_list.clj<pre><code>(def recent-songs [])\n\n(defn add-song [song song-list]\n  (cons song song-list))\n</code></pre> <p><code>recent-songs</code> is passed into the <code>add-song</code> function as an argument, <code>song-list</code> to keep the design of <code>add-song</code> function pure (no side-effects).  This design also provides greater scope to using the <code>add-song</code> function, as any song list can be added to, rather than hard-coding <code>recent-songs</code> list.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-added-to-top-of-list","title":"Test song added to top of list","text":"<p>As the song list shows recently played songs, new songs added should be at the top of the list.</p> <p>The list should not contain duplicate entries for a song.</p> Test songs added to top of list test/playground/song_list_test.clj<pre><code>(deftest recently-added-song-first-test\n\n  (testing \"most recent song should be first in the list when empty list\"\n    (is (=\n         (first (add-song \"Daft Punk - Get Lucky\" recent-songs))\n         \"Daft Punk - Get Lucky\")))\n\n  (testing \"most recent song should be first in list when adding multiple songs\"\n    (is (=\n         (first\n          (-&gt;&gt; recent-songs\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\")))\n\n  (testing \"most recent song should be first in list when adding a repeated song\"\n    (is (=\n         (first\n          (-&gt;&gt; recent-songs\n               (add-song \"Pharrell Williams - Happy\")\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\")))\n\n  (testing \"most recent song should be first in list when adding a repeated song\"\n    (is (not=\n         (last\n          (-&gt;&gt; recent-songs\n               (add-song \"Pharrell Williams - Happy\")\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\"))))\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#add-song-to-start-of-list","title":"Add song to start of list","text":"<p>Create a function to add a song to the start of the song list.</p> Function to add song to list <p>The <code>add-song</code> function takes the name of a song and the song list to which it will be added.</p> <p>A Thread-last macro <code>-&gt;&gt;</code> is used to pass the song list over two functions.</p> <p>The <code>song-list</code> is first passed to the <code>remove</code> expression as its last argument.  This expression will remove any occurrence of the new song we want to add from the <code>song-list</code>.</p> <p>The results of the <code>remove</code> expression are then passed to the <code>cons</code> expression as its last argument.  The <code>cons</code> expression simply adds the new song to the start of the list, making it the most recent song.</p> src/playground/song_list.clj<pre><code>(def recent-songs [])\n\n(defn add-song [song song-list]\n  (-&gt;&gt; song-list\n       (remove #(= song %))\n       (cons song)))\n</code></pre> <p><code>recent-songs</code> is passed into the <code>add-song</code> function as an argument, <code>song-list</code> to keep the design of <code>add-song</code> function pure (no side-effects).  This design also provides greater scope to using the <code>add-song</code> function, as any song list can be added to, rather than hard-coding <code>recent-songs</code> list.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/","title":"Salary Slip Kata","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/salary-calculator\n</code></pre>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#problem-description","title":"Problem description","text":"<p>A typical salary slip contains employee details like employee id, employee name and their monthly salary details like their gross salary, national insurance contributions, tax-free allowance, taxable income and tax payable.</p> <p>Salary slips are generated each month for every employee.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#acceptance-criteria","title":"Acceptance criteria","text":"<ul> <li>Salary slip generator should receive an employee with its Employee Id, Employee Name and Annual Gross Salary</li> <li>Salary slip should contain the Employee ID, Employee Name, Gross Salary, National Insurance contributions, Tax-free allowance, Taxable income and Tax payable for the month</li> <li>The entry point should be the following public function API</li> </ul> <pre><code>(defn salary-slip-generator\n  \"\"\n  [employee]\n  ,,,)\n</code></pre>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iterations","title":"Iterations","text":"<p>Each iteration adds more rules to the calculation. Some iterations also introduce new fields to the salary slip.</p> <p>In a given iteration, all the salary slips contain the same number fields for each employee (if a tax or contribution does not apply for a given employee, just put \u00a30.00).</p> <p>This means that for each iteration you will need to add fields to the <code>SalarySlip</code> class. In the first iteration, <code>SalarySlip</code> only contains the Employee ID, Employee Name and Monthly Gross Salary.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-1-for-an-annual-salary-of-500000","title":"Iteration 1: for an annual salary of \u00a35,000.00","text":"<p>This is the most basic case.</p> <ul> <li>Given I have an employee John J Doe with an annual gross salary of \u00a35,000.00</li> <li>When I generate a monthly salary slip for the employee</li> <li>Then the monthly salary slip should contain the below<pre><code>   Employee ID: 12345\n   Employee Name: John J Doe\n   Gross Salary: \u00a3416.67\n</code></pre> </li> </ul> <p>Calculation rules:</p> <ul> <li>Monthly Gross Salary: The monthly gross salary is the employee's annual gross salary divided by 12</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-2-for-an-annual-gross-salary-of-906000","title":"Iteration 2: for an annual gross salary of \u00a39,060.00","text":"<p>Here we introduce the National Insurance contribution</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a3755.00\n       National Insurance contributions: \u00a310.00\n</code></pre> <p>Calculation rules:</p> <ul> <li>National Insurance contributions: Any amount of money earned above a gross annual salary of \u00a38,060.00 is subject to a National Insurance contribution of 12%</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-3-for-an-annual-gross-salary-of-1200000","title":"Iteration 3: for an annual gross salary of \u00a312,000.00","text":"<p>This employee also needs to pay taxes</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a31,000.00\n       National Insurance contributions: \u00a339.40\n       Tax-free allowance: \u00a3916.67\n       Taxable income: \u00a383.33\n       Tax Payable: \u00a316.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Taxable income: Any amount of money earned above a gross annual salary of \u00a311,000.00 is taxed at 20%</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-4-for-an-annual-gross-salary-of-4500000","title":"Iteration 4: for an annual gross salary of \u00a345,000.00","text":"<p>This employee pays a higher band of National Insurance and Income Tax.</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a33,750.00\n       National Insurance contributions: \u00a3352.73\n       Tax-free allowance: \u00a3916.67\n       Taxable income: \u00a32,833.33\n       Tax Payable: \u00a3600.00\n</code></pre> <p>Calculation rules:</p> <ul> <li>Taxable income (higher rate): Any amount of money earned above a gross annual salary of \u00a343,000.00 is taxed at 40%</li> <li>National Insurance (higher contributions): Any amount of money earned above a gross annual salary of \u00a343,000.00 is only subject to a 2% NI contribution</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-5-for-annual-gross-salaries-of-10100000-11100000-12200000-and-15000000","title":"Iteration 5: for annual gross salaries of \u00a3101,000.00; \u00a3111,000.00; \u00a3122,000.00 and \u00a3150,000.00","text":"<p>For high earners, the tax-free allowance decreases.</p> <p>The monthly salary slips should contain the below (respectively):</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a38,416.67\n       National Insurance contributions: \u00a3446.07\n       Tax-free allowance: \u00a3875.00\n       Taxable income: \u00a37,541.67\n       Tax Payable: \u00a32,483.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a39,250.00\n       National Insurance contributions: \u00a3462.73\n       Tax-free allowance: \u00a3458.33\n       Taxable income: \u00a38,791.67\n       Tax Payable: \u00a32,983.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a310,166.67\n       National Insurance contributions: \u00a3481.07\n       Tax-free allowance: \u00a30.00\n       Taxable income: \u00a310,166.67\n       Tax Payable: \u00a33,533.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a312,500.00\n       National Insurance contributions: \u00a3527.73\n       Tax-free allowance: \u00a30.00\n       Taxable income: \u00a312,500.00\n       Tax Payable: \u00a34,466.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Tax-free allowance: When the Annual Gross Salary exceeds \u00a3100,000.00, the tax-free allowance starts decreasing. It decreases by \u00a31 for every \u00a32 earned over \u00a3100,000.00. And this excess is taxed at the Higher rate tax.</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-6-for-an-annual-gross-salary-of-16000000","title":"Iteration 6: for an annual gross salary of \u00a3160,000.00","text":"<p>The employee goes into the additional rate band.</p> <p>The monthly salary slip should contain the below:</p> <pre><code>      Employee ID: 12345\n      Employee Name: John J Doe\n      Gross Salary: \u00a313,333.33\n      National Insurance contributions: \u00a3544.40\n      Tax-free allowance: \u00a30.00\n      Taxable income: \u00a313,333.33\n      Tax Payable: \u00a34,841.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Income tax (additional rate band) : Any amount of money earned above a gross annual salary of \u00a3150,000.00 is taxed at 45%</li> </ul> Practicalli Salary Slip Kata <p>Salary slip kata - Devoxx 2019</p> <pre><code>(ns salary-slip-kata.core\n  \"Developer Anarchy by Fred George\n   - made devs write the same solution in different languages\n   -- helps devs master the business domain\n   -- helps devs master technology domain\")\n\n(defn- national-insurance-contribution\n  \"Calculate the national insurance contribution due for a given annual salary.\n\n  ---------------------+-------------------------+--------\n  Band                 | NI deductible income    | NI Rate\n  ---------------------+-------------------------+--------\n  No contributions     | Up to \u00a38,060.00         |    0%\n  Basic contributions  | \u00a38,060.00 to \u00a343,000.00 |   12%\n  Higher contributions | over \u00a343,000.00         |    2%\n  ---------------------+-------------------------+-------- \"\n\n  [annual-gross-salary]\n  ;; add a cond statement to return the calculate the value with respect to the band.\n  (* annual-gross-salary 0.12))\n\n\n;; taxable income\n;; ---------------------+---------------------------+---------\n;; Band                 | Taxable income            | Tax rate\n;; ---------------------+---------------------------+---------\n;; Personal Allowance*  | Up to \u00a311,000.00          |    0%\n;; Basic rate           | \u00a311,000.00 to \u00a343,000.00  |   20%\n;; Higher rate          | \u00a343,000.00 to \u00a3150,000.00 |   40%\n;; Additional rate      | over \u00a3150,000.00          |   45%\n;; ---------------------+---------------------------+---------\n\n\n(defn salary-slip\n  \"Creates a salary slip for a person\n\n  Specifically for employee of 24K annual salary\"\n\n  [{:keys [employee-id\n           employee-name\n           annual-gross-salary]}]\n  (let [tax-free-allowance 11000\n        taxable-income     (- annual-gross-salary\n                              tax-free-allowance)]\n    {:employee-id        employee-id\n     :employee-name      employee-name\n     :gross-salary       (/ annual-gross-salary 12)\n     :national-insurance (national-insurance-contribution annual-gross-salary)\n     :tax-free-allowance tax-free-allowance\n     :taxable-income     taxable-income\n     :tax-payable        (* taxable-income 0.20)}))\n</code></pre>"},{"location":"testing/","title":"Testing in Clojure","text":"<p>Testing is supported in Clojure with a range of testing libraries and test runners.</p>"},{"location":"testing/#unit-test","title":"Unit Test","text":"<p>The unit of test in Clojure is the function, so functions are defined that test other functions.</p> <p>clojure.test namespace is part of the Clojure standard library and provides assertion based testing and functions to run tests.</p> <p>Practicalli Unit Testing Guide Using Test Runners</p>"},{"location":"testing/#generative-testing","title":"Generative testing","text":"<p>Define specifications for values to confirm information coming into and leaving a Clojure service are of the correct form.</p> <p>Generate test data from value specifications to verify the behaviour of functions, creating diverse sets of data for extensive testing.</p> <p>Define specifications for functions to validate the correct form of values are passed and returned from a function.</p> <p>Define value and function specifications with Cloure Spec Generative Testing with Clojure Spec</p>"},{"location":"testing/#performance-testing","title":"Performance testing","text":"<p>Test individual expressions through to application and load testing one or more services.</p> <ul> <li>time - simple results of evaluating an expression</li> <li>criterion - a realistic measure of performance for clojure expressions</li> <li>Gatling - open source &amp; commercial load test tool for web applications</li> <li>clj-gatling - wrapper around Gatling which enables tests to be expressed in Clojure.</li> </ul>"},{"location":"testing/#behaviour-driven-development-frameworks","title":"Behaviour Driven Development frameworks","text":"<p>Although not widely used in the Clojure community, there are several approaches to develop and test software using Behaviour Driven Development.</p> <p>BDD: Given, When, Then and scenario approach to outside in software testing</p> <ul> <li>Scenari - executable specification / BDD in Clojure</li> <li>kaocha-cucumber - support for Cucumber tests in the gerkin format</li> <li>speclj - TDD/BDD framework for Clojure and ClojureScript based on RSpec.</li> </ul> <p>Alternative BDD libraries are discussed at https://github.com/gphilipp/bdd-guide-clojure</p>"},{"location":"testing/#articles-on-testing-in-clojure","title":"Articles on testing in Clojure","text":"<ul> <li>Clojure test runner of my dreams</li> <li>Example based unit testing in Clojure</li> <li>TDD in Clojure at Funding Circle</li> <li>Bolth - a more humane test runner</li> <li>Announcing kaocha a new and improved clojure test runner</li> <li>Scenarios as code - Clojure Remote presentation</li> <li>Load testing with Gatling and Clojure - JUXT.pro</li> </ul>"},{"location":"testing/clojure-test/","title":"Unit Testing with <code>clojure.test</code>","text":"<p><code>clojure.test</code> is a test library that is already part of Clojure and test package hierarchy is typically created (e.g. when generating Clojure projects with Leiningen).</p> <p>As with other unit testing libraries you use <code>clojure.test</code> to write test.  These tests are defined as functions that contain one or more assertions.</p> <p>As a general guideline, a Clojure test function should test a specific Clojure function.</p>"},{"location":"testing/clojure-test/#hintwhat-to-test","title":"Hint::What to test","text":"<p>Define a <code>deftest</code> for every public functions within a namespace, so the contract / api for each namespace is testable and will highlight obvious regressions. The <code>testing</code> function can be used to group assertions for a particular <code>deftest</code>, so different aspects of the tests can be grouped together.</p> <p>Test reports contain only the names of the <code>deftest</code> functions, as there are no names with <code>testing</code></p> <p><code>clojure.spec</code> provides another way to define a contract around your functions and data structures.  It also includes generative testing approach to broaden the test data used to test your functions.</p>"},{"location":"testing/clojure-test/#test-namespaces","title":"Test namespaces","text":"<p><code>clojure.test</code> needs to be included in the namespace in order to use the functions that namespace provides.</p> <p>The recommended syntax is to <code>:refer</code> the specific functions which makes those functions available as if they were defined in the current namespace.</p> <p>The namespace that is under test also needs to be included and and its recommended that you use the alias <code>SUT</code> for system under test.  The test namespace matches the namespace you are testing, with the addition of <code>-test</code> to the name.</p> <pre><code>(ns my-clojure-app.core-test\n  (:require [clojure.test :refer [deftest deftest- testing is]]\n            [my-clojure-app.core :as SUT ]))\n</code></pre>"},{"location":"testing/clojure-test/#writing-an-assertion","title":"Writing an assertion","text":"<p>An assertion is where you compare an expected result with the result of calling a function.  If the assertion is true, then then it is a pass.  If the assertion is false, then its a fail.</p> <p>The form of an assertion takes a form <code>(is (comparator expected-value function-call))</code></p> <p>Some simple examples include</p> <pre><code>(is (= 42 (* 6 7)))\n\n(is (not= 24 (* 6 7)))\n</code></pre>"},{"location":"testing/clojure-test/#defining-a-test","title":"Defining a test","text":"<p><code>deftest</code> is used to define a function that will test a similarly named function from the <code>src</code> tree.  The test function name should match the function it is testing with <code>-test</code> added to the end.</p> <p><code>testing</code> function allows you to group one or more assertions</p> <p><code>is</code> defines an assertion</p> <pre><code>(deftest adder-test\n  (testing \"Using a range of numbers to test the adder\"\n    #_(is (= 0 1))\n    (is (= (+ 1 2) (adder 1 2)) \"Adding 1 and 2\")\n    (is (= (+ 1 -2) (adder 1 -2)) \"Adding 1 and -2\")\n    #_(is (not (= (+ 1 2)) (adder \"a\" \"b\")) \"Adding strings as negative test\")\n    (is (false? (= 0 1)) \"A simple failing test\")\n    (is (false? (= 0 (adder 3 4))) \"Purposefully using failing data\")))\n</code></pre>"},{"location":"testing/integration-testing/","title":"Integration Testing","text":"<p>See the continuous integration section</p>"},{"location":"testing/test-runners/","title":"Test Runners","text":"<p>A test runner is used to run one or more unit tests in a project and report the results.  When there are failing tests, a test runners show details of how the failing test, showing actual and expected values.</p> <p>Test runners may support specification testing with clojure.spec, checking data and functions conform to their specifications.</p> <p>Test runners are called from either a Clojure editor, as a command line tool or within a continuous integration workflow.</p> <p>Regularly run tests in a project to ensure implementations and design decisions made so far have not regressed.</p> Test runner Type Summary cognitect-labs test runner clj Simple test runner cljs-test-runner cljs Run all ClojureScript tests with one simple command. Kaocha clj, cljs Full featured test runner CIDER test runner clj CIDER built in test runner <p> CIDER test runner is ideal if using Emacs for Clojure development, as its build into CIDER.</p> <p>Practicalli Recommends Kaocha test runner</p> <p>Kaocha is a very feature rich test runner for Clojure and ClojureScript, BDD style cucumber tests, coverage and junit style reporting.</p> <p> Practicalli Clojure CLI Config - test runner aliases</p> <p> Practicalli Clojure CLI Config contains several aliases for test runners</p> <ul> <li><code>:test/env</code> adds the <code>test</code> directory to the class path and <code>org.clojure/test.check</code> library</li> <li><code>clojure -X:test/run</code> run Kaocha test runner</li> <li><code>clojure -X:test/watch</code> run Kaocha test runner in watch mode, running on file changes</li> <li><code>clojure -M:test/cljs</code>  run Kaocha ClojureScript test runner</li> <li><code>clojure -X:test/cognitect</code> simple to use Cognitect test runner</li> <li><code>:lib/kaocha</code> adds Kaocha as a library to the class path, enabling Kaocha to run from an editor, e.g. Emacs Cider with Kaocha test runner</li> </ul> <p>Practicalli REPL Reloaded aliases <code>:repl/reloaded</code> &amp; <code>:dev/reloaded</code> also support Kaocha test runner</p>"},{"location":"testing/test-runners/aero/","title":"Aero","text":"<p>juxt/aero is used to read the kaocha configuration, so reader literals such as #env, #merge, #ref, and #include can be used.</p> <p>Set up profiles for different stages of the development workflow, dev, test, prod, etc.  Each profile has a different configuration making it very easy to switch</p> <pre><code>{:port 8000\n :database #profile {:prod \"datomic:dev://localhost:4334/my-prod-db2\"\n                     :test \"datomic:dev://localhost:4334/my-test-db\"\n                     :default \"datomic:dev://localhost:4334/my-db\"}\n :known-users [{:name \"Alice\"} {:name \"Betty\"}]}\n</code></pre> <p>Then in application startup function or a component lifecycle library (mount, component, integrant) read in a specific profile</p> <pre><code>(aero.core/read-config \"config.edn\" {:profile :prod})\n</code></pre>"},{"location":"testing/test-runners/congnitect-labs-test-runner/","title":"Cognitect Labs Test Runner","text":"<p>Cognitect Labs test-runner is a test runner for Clojure projects defined with <code>deps.edn</code> and using <code>clojure.test</code> library which is part of the Clojure standard library.</p> <p>test-runner aims to provide a standard way to discover and run unit and property-based tests, in a simple to use and lightweight tool.</p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#add-test-runner","title":"Add test-runner","text":"<p>Make test-runner available to all projects by adding it to <code>~/.clojure/deps.edn</code>.  Or add test-runner to specific projects by adding an alias to the project <code>deps.edn</code> file.  Include <code>:extra-paths</code> configuration to include the standard <code>test</code> directory so that the runner has access to the test code.</p> Practicalli Clojure CLI ConfigAlias Definition <p>  Practicalli Clojure CLI Config provides aliases for test runner tools, including <code>:test/congnitect</code> for running Cognitect Labs test runner</p> <p>Add an alias to run Cognitect Labs test runner, either in the project or user <code>deps.edn</code> configuration file. ```clojure   :test/cognitect   {:extra-paths [\"test\"]    :extra-deps  {com.cognitect/test-runner                  {:git/url \"https://github.com/cognitect-labs/test-runner.git\"                   :sha     \"f7ef16dc3b8332b0d77bc0274578ad5270fbfedd\"}}    :main-opts   [\"-m\" \"cognitect.test-runner\"]}</p> <p>```</p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#run-test-runner","title":"Run test runner","text":"<p>Run the Cognitect Labs test runner via the command line</p> <pre><code>clojure -M:test/cognitect\n</code></pre> <p>The <code>cognitect.test-runner/-main</code> function is called which scans the <code>test</code> directory of the current project tests defined using <code>clojure.test</code>,  running all tests found.</p> <p>A summary is returned with the results of running the tests.</p> <p></p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#command-line-options","title":"Command line options","text":"Flag Description -d, --dir DIRNAME Name of the directory containing tests. Defaults to \"test\". -n, --namespace SYMBOL Symbol indicating a specific namespace to test. -r, --namespace-regex REGEX Regex for namespaces to test. Defaults to #\".*-test$\"  (i.e, only namespaces ending in '-test' are evaluated) -v, --var SYMBOL Symbol indicating the fully qualified name of a specific test. -i, --include KEYWORD Run only tests that have this metadata keyword. -e, --exclude KEYWORD Exclude tests with this metadata keyword. -H, --test-help Display this help message <p>Options can be used multiple times in one command, for a logical OR effect. For example, the following command runs all tests in the <code>practicalli.data.survey</code> and <code>practicalli.services.survey-report</code> namespaces that are found in the <code>src</code> and <code>test</code> directories</p> <pre><code>clojure -M:test/cognitect -d test -d src -n practicalli.data.survey -n practicalli.services.survey-report\n</code></pre>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#test-selectors","title":"Test Selectors","text":"<p>Selectively running tests by including and excluding test categories, from the meta-data added to test definitions, i.e. <code>deftest</code>.</p> <pre><code>(deftest ^:integration test-live-system\n  (is (= 200 (:status (http/get \"http://example.com\")))))\n</code></pre> <p>Use the <code>--include</code> flag with the test runner to specify specific categories of tests</p> <pre><code>clojure -M:test-runner-cognitect --include :integration\n</code></pre> <p>The <code>--include</code> flag can be used multiple times, defining a test category with each include.</p> <pre><code>clojure -M:test-runner-cognitect --include :integration --include :persistence\n</code></pre> <p>Clojure Unit Test - categories example integration and develop tests</p> <p><code>--exclude</code> flag runs all tests except those in the given category</p> <pre><code>clojure -M:test/cognitect --exclude :integration\n</code></pre> <p>Exclusions take priority over inclusions if both flags are included.</p>"},{"location":"testing/test-runners/example-projects/","title":"Example projects","text":"<ul> <li>TDD Kata: Recent Song-list - simple tests examples</li> <li>Codewars: Rock Paper Scissors (lizard spock) solution - <code>and</code> examples</li> <li>practicalli/numbers-to-words - overly verbose example, ripe for refactor</li> <li>practicalli/codewars-guides - deps.edn projects</li> <li>practicalli/exercism-clojure-guides - Leiningen projects</li> </ul>"},{"location":"testing/test-runners/example-projects/#sean-corfield-user-manager","title":"Sean Corfield - user manager","text":"<p>User manager has unit tests that also include an embedded database.  Tests can run with the Cognitect Labs test runner.</p> <p><code>:test</code> alias includes the test path and a dependency for the H2 database</p> <p>Cognitect Labs test runner included in the project <code>deps.edn</code> file as <code>:runner</code></p> <p><code>clojure -M:test:runner</code> will run the Cognitect Labs runner and include the dependency to run the in-memory database used for the tests.</p>"},{"location":"testing/test-runners/example-projects/#using-koacha-with-sean-corfield-user-manager","title":"Using koacha with Sean Corfield user manager","text":"<p>Adding a <code>test.edn</code> file is not sufficient for testing this project with lambdaisland/kaocha, as the H2 dependency is also needed.</p> <p>Create a <code>bin/koacha</code> script and add the extra alias</p> <pre><code>#!/usr/bin/env bash\nclojure -M:test:test-runner-kaocha \"$@\"\n</code></pre>"},{"location":"testing/test-runners/example-projects/#status-monitor","title":"Status Monitor","text":"<p>Status monitor is a Leiningen project.</p> <p>Include a <code>:kaocha</code> profile in the <code>project.clj</code> file, adding the koacha dependency.  The <code>:kaocha</code> alias sets the main namespace and uses the kaocha profile.</p> <pre><code>  {:dev    {:dependencies [[javax.servlet/servlet-api \"2.5\"]\n                           [ring/ring-mock \"0.3.2\"]]}\n   :kaocha {:dependencies [[lambdaisland/kaocha \"1.0.632\"]]}}\n  :aliases {\"kaocha\" [\"with-profile\" \"+kaocha\" \"run\" \"-m\" \"kaocha.runner\"]}\n</code></pre> <p><code>lein kaocha</code> will run all the tests</p>"},{"location":"testing/test-runners/kaocha-test-runner/","title":"LambdaIsland Kaocha Test Runner","text":"<p> lambdaisland/kaocha (cow-cha) is a comprehensive test runner that support unit testing and <code>clojure.spec</code> generative testing.  Clojure and ClojureScript languages are supported.</p> <p>Kaocha is highly configurable via a <code>tests.edn</code> configuration file in the root of the project.</p>"},{"location":"testing/test-runners/kaocha-test-runner/#clojure-cli-config","title":"Clojure CLI Config","text":"Practicalli Clojure CLI ConfigAlias Definition <p>  Practicalli Clojure CLI Config configuration contains aliases to run kaocha test runner, using either the <code>-X</code> or <code>-M</code> execution flag.</p> <ul> <li><code>:test/run</code> - run all tests in the project, stopping on first failing test</li> <li><code>:test/watch</code> - watching for file changes and run all tests in the project, stopping on first failing test</li> <li><code>:test/env</code> - add supporting paths and libraries for testing projects</li> </ul> <p>Each alias includes <code>:extra-paths [\"test\"]</code> to include the <code>test</code> directory on the class path, enabling Koacha test runner to find the unit test code.</p> <p>Define an alias in the project or user <code>deps.edn</code> configuration.</p> <p>For CI services such as CircleCI or GitLabs, add an alias for kaocha to the project <code>deps.edn</code> file.</p> <p>Alias definitions for LambdaIsland/Kaocha test runner</p> <p>Aliases support the <code>-M</code> (clojure.main) and <code>-X</code> (clojure.exec) execution options with Clojure CLI. <pre><code>:test/run\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.77.1236\"}}\n :main-opts   [\"-m\" \"kaocha.runner\"]\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:fail-fast? true\n             :randomize? false}}\n\n;; Kaocha test runner in watch mode\n;; clojure -X:test/watch\n:test/watch\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.77.1236\"}}\n :main-opts   [\"-m\" \"kaocha.runner\" \"--watch\" \"--fail-fast\" \"--skip-meta\" \":slow\"]\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:watch? true\n             :randomize? false\n             :fail-fast? true}}\n</code></pre></p> <p>Libraries and directories containing code to support testing projects can be added to the <code>:test/env</code> alias <pre><code>:test/env\n{:extra-paths [\"test\"]\n :extra-deps  {org.clojure/test.check {:mvn/version \"1.1.1\"}}}\n</code></pre></p> <p>Alias definitions should include <code>:extra-paths [\"test\"]</code> to add the <code>test</code> directory on the class path, enabling Koacha test runner to find the unit test code.</p>"},{"location":"testing/test-runners/kaocha-test-runner/#run-kaocha","title":"Run Kaocha","text":"<p>Kaocha can be run via make tasks, Clojure CLI, or by creating a <code>kaocha</code> script.</p> <p>Babashka task runner could also be used to develop tasks to run kaocha</p> MakeClojure CLIKaocha script <p>  Practialli Makefile contains tasks for testing Clojure projects with Kaocha (and many other common Clojure development tasks)</p> Practicalli Makefile targets for unit testing <p>Practicalli Makefile includes the following targets for Kaocha test runner Makefile<pre><code># ------- Testing -------------------- #\n\ntest-config:  ## Run unit tests - stoping on first error\n    $(info --------- Runner Configuration ---------)\n    clojure -M:test/env:test/run --print-config\n\ntest-profile:  ## Profile unit test speed, showing 3 slowest tests\n    $(info --------- Runner Profile Tests ---------)\n    clojure -M:test/env:test/run --plugin  kaocha.plugin/profiling\n\ntest:  ## Run unit tests - stoping on first error\n    $(info --------- Runner for unit tests ---------)\n    clojure -X:test/env:test/run\n\n\ntest-all:  ## Run all unit tests regardless of failing tests\n    $(info --------- Runner for all unit tests ---------)\n    clojure -X:test/env:test/run :fail-fast? false\n\ntest-watch:  ## Run tests when changes saved, stopping test run on first error\n    $(info --------- Watcher for unit tests ---------)\n    clojure -X:test/env:test/run :watch? true\n\ntest-watch-all:  ## Run all tests when changes saved, regardless of failing tests\n    $(info --------- Watcher for unit tests ---------)\n    clojure -X:test/env:test/run :fail-fast? false :watch? true\n\n# ------------------------------------ #\n</code></pre></p> <p>Run all tests using the following command from the root of the Clojure project. Kaocha stops if there is a failing task, saving time on running the whole test suite. <pre><code>make test\n</code></pre></p> <p>Use the <code>test-all</code> target to run all unit tests regardless of failures (execept compiler errors)</p> <pre><code>make test-all\n</code></pre> <p>Continually run tests by watching for changes using the <code>:test/watch</code> alias.  If a test fails, Koacha will stop the test run and restart from the failing test when a change is detected.  Use <code>watch-all</code> if all tests should run regardless of failure.</p> <pre><code>make test-watch\n</code></pre> <p> </p> <p>  Practicalli Clojure CLI Config configuration contains aliases to run kaocha test runner, using either the <code>-X</code> or <code>-M</code> execution flag.</p> <p>Run Kaocha using the <code>clojure</code> command in a terminal, using the <code>:test/run</code> which runs all the tests in a project unless a test fails, then kaocha will stop.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Pass <code>:fail-fast? false</code> as an argument to run all tests regardless of test failure.</p> <pre><code>clojure -X:test/run :fail-fast? false\n</code></pre> <p>Continually run tests by watching for changes using the <code>:test/watch</code> alias.  If a test fails, Koacha will stop the test run and restart from the failing test when a change is detected.</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Kaocha recommends adding a <code>bin/kaocha</code> script to each project, although this is optional.  The script calls <code>clojure</code> with a suitable alias and allows for arguments to be passed to the command using <code>\"$@\"</code>.  Command line options will over-ride the same options in the <code>tests.edn</code> file.</p> <p>bin/kaocha<pre><code>#!/usr/bin/env bash\nclojure -M:test/runner \"$@\"\n</code></pre> Use the <code>-M</code> execution option to pass command line flags to the Kaocha test runner.</p> <pre><code>kaocha --fail-fast\n</code></pre>"},{"location":"testing/test-runners/kaocha-test-runner/#configuring-kaocha","title":"Configuring Kaocha","text":"<p>Kaocha can be configure by options in a <code>tests.edn</code> configuration file and options passed via the command line (typically added to the <code>bin/kaocha</code> script).</p> <p>Create a <code>tests.edn</code> file in the root of the project directory and add the default configuration.</p> tests.edn<pre><code>#kaocha/v1 {}\n</code></pre> <p>The <code>tests.edn</code> file and command line options combine to make the complete configuration for the projects in the test.</p> <p><code>make test-config</code> runs <code>clojure -M:test/run --print-config</code> to print out the current kaocha configuration.</p> <p> </p> <p>Use the default configuration as the basis for customising kaocha test runner for the current project.</p> Alternative kaocha configuration with aero <p>juxt/aero reader literals such as #env, #merge, #ref, and #include can be used to provide different options to the kaocha configuration. For example, a file change watcher can be configured to run unless kaocha is running in CI server environment.</p> <p><code>:kaocha/watch #profile {:default true :ci false}</code></p>"},{"location":"testing/test-runners/kaocha-test-runner/#plugins","title":"Plugins","text":"<p>Much of the functionality of Kaocha is provide by plugins</p> <ul> <li>profiling - lists the slowest tests for each test category</li> <li>cucumber - bdd style test</li> <li>junit-xml reports - format used by Continuous Integration servers to display results</li> </ul>"},{"location":"testing/test-runners/kaocha-test-runner/#profiling","title":"Profiling","text":"<p>Show the 3 slowest tests for each category of test, after the test results</p> MakeClojure CLIKaocha Script <p>As a command line option: <pre><code>make test-profile\n</code></pre></p> <p>Pass the profiling plugin as an argument to the Clojure CLI alias using the <code>-M</code> (clojure.main) execution option <pre><code>clojure -M:test/env:test/run --plugin kaocha.plugin/profiling\n</code></pre></p> <p>As a command line option: <pre><code>bin/kaocha --plugin kaocha.plugin/profiling\n</code></pre></p> <p>Or add the profile plugin to the <code>test.edn</code> configuration</p> <pre><code>#kaocha/v1\n{:plugins [:kaocha.plugin/profiling]}\n</code></pre>"},{"location":"testing/test-runners/kaocha-test-runner/#example-testsedn","title":"Example tests.edn","text":"<p> Practicalli Banking-on-Clojure project is a web application backed by a relational database, using kaocha as the test runner.</p> <p><code>:kaocha/tests</code> defines two types of tests.  The hash-map containing <code>:kaocha.testable/id :unit</code> defines the configuration for unit tests using <code>clojure.test</code>.  The hash-map containing <code>:kaocha.testable/id :generative-fdef-checks</code> are generative tests using clojure spec.</p> <p><code>:kaocha/color?</code> and <code>:kaocha/watch</code> use a value dependent on the <code>#profile</code> kaocha is run under.</p> <p>Banking on Clojure project - Kaocha test.edn configuration</p> <pre><code>#kaocha/v1\n{:kaocha/tests\n [{:kaocha.testable/id      :unit\n   :kaocha.testable/type    :kaocha.type/clojure.test\n   :kaocha/ns-patterns      [\"-test$\"],\n   :kaocha/source-paths     [\"src\"],\n   :kaocha/test-paths       [\"test\"],\n   :kaocha.filter/skip-meta [:kaocha/skip]}\n\n  {:kaocha.testable/id            :generative-fdef-checks\n   :kaocha.testable/type          :kaocha.type/spec.test.check\n   :kaocha/source-paths           [\"src\"]\n   :kaocha.spec.test.check/checks [{:kaocha.spec.test.check/syms            :all-fdefs\n                                    :clojure.spec.test.check/instrument?    true\n                                    :clojure.spec.test.check/check-asserts? true\n                                    :clojure.spec.test.check/opts           {:num-tests 10}}]}\n  ]\n\n :kaocha/reporter [kaocha.report/documentation]\n\n :kaocha/color? #profile {:default true\n                          :ci      false}\n\n ;; Run tests of file changes, unless running in CI server\n :kaocha/watch #profile {:default true :ci false}\n\n :kaocha/fail-fast? true\n\n :kaocha.plugin.randomize/randomize? false\n\n :kaocha/plugins\n [:kaocha.plugin/randomize\n  :kaocha.plugin/filter\n  :kaocha.plugin/capture-output\n  :kaocha.plugin.alpha/spec-test-check]\n\n :kaocha.plugin.capture-output/capture-output? true\n }\n</code></pre> <p>The configuration shows how to explicitly configure different sections, although configuration could be streamlined by using more default values.</p>"},{"location":"testing/unit-testing/","title":"Clojure Unit Testing","text":"<p>The function is the unit under test in Clojure.  All public functions that form the API of their respective namespace should have a matching test, i.e. <code>(deftest)</code> definition.</p> <p><code>clojure.test</code> namespace provides functions for defining and running unit tests and is available in the Clojure library for any project to use.</p> <p></p>"},{"location":"testing/unit-testing/#unit-test-principles","title":"Unit Test Principles","text":"<ul> <li>A <code>test</code> namespace for each <code>src</code> namespace under test</li> <li>A <code>deftest</code> function for each function under test, named after the function its testing with <code>-test</code> at the end of the name</li> <li>Multiple assertions (<code>is</code> <code>are</code>) for one function</li> <li><code>is</code> defines an assertion returning true (test pass) or false (test fail), typically a comparison between a known value and the result of a function call</li> <li><code>are</code> to testing similar functionality with different data sets (or use generative testing)</li> <li><code>testing</code> to logically group assertions and provide a meaningful description of that grouping (easier to identify tests when they fail)</li> <li><code>use-fixtures</code> to call fixture functions that setup and tear down any state required for test(s) to run</li> <li>Test API rather than implementation</li> <li>test generic helper or private functions through public functions of each namespace (minimise test churn and time to run all tests)</li> <li><code>^:helper</code> meta-data on <code>deftest</code> for more generic functions, to skip those tests via a test selector</li> <li>Use generative testing to create more maintainable test code with more extensive range of data</li> <li>Use test selectors with a test runner to selectively run tests and optimise speed of test runs</li> <li>Limit mocking of systems to integration tests (although mocking data is good everywhere)</li> </ul> Code should evaluate or have line comments <p>All Clojure code should be valid syntax and able to be evaluated (compiled), even code within a <code>(comment )</code> expression or after a <code>#_</code> reader comment.</p> <p>Code commented with a line comment, <code>;;</code>, will not be read by Clojure and cannot cause compilation errors when evaluated</p>"},{"location":"testing/unit-testing/#running-tests","title":"Running tests","text":"<p>Test runners can run be run in the REPL used for development or run separately via the command line and continuous integration tasks.</p> <p></p>"},{"location":"testing/unit-testing/#run-tests-in-editor-connected-repl","title":"Run tests in Editor connected REPL","text":"<p>Using an editor connected REPL keeps the workflow in one tool and helps maintain focus. Using editor commands to run the tests and navigable error reports provides an effective flow to run and debug issues.</p> <p>Ensure <code>test</code> directory is on the class path when evaluating tests in the REPL, otherwise the <code>(deftest)</code> test definitions may not be found.</p> <p>If functions or their associated tests are changed, they should be evaluated in the REPL before running tests to ensure those changes are loaded into the REPL.</p> <p>If renaming a function or <code>deftest</code>, the original name should be removed from the REPL to avoid phantom tests (older definitions of tests that were evaluated in the REPL and still run, even though those tests are no longer in the source code).</p> <p>Editors may include a command to remove function or test definitions, e.g. CIDER has <code>undef</code> command</p> <p>The original name can also be removed using Clojure <code>(ns-unmap 'namespace 'name)</code>, where namespace is where the name of the function or test is defined and name is the name of the function or test.</p> <pre><code>(ns practicalli.system-monitor)                ; namespace definition\n(defn dashboard [] ,,,)                        ; original function name\n(defn dashboard-page [] ,,,)                   ; new function name\n(undef 'practicalli.system-monitor 'dashboard) ; remove original function name\n</code></pre> <p>Stop and start the REPL process ensures all function and tests are correctly loaded</p>"},{"location":"testing/unit-testing/#command-line-test-runners","title":"Command line test runners","text":"<p>Command line test runners (i.e. koacha, Cognitect Labs) load function and test definitions from the source code files each time, ensuring tests are run and a clean REPL state is created on each run. This clearly defined REPL state is especially valuable for running repeatable integration tests.</p> <p>Automate running the tests using a watch process,  giving instant fast feedback, especially when displaying both the editor and test runner command line.</p> <p>test runner can be configure to run only selective tests (i.e kaocha)</p> <p>Run all tests (including integration tests) via the command line before pushing commits to ensure all changes to the code have been tested.</p> <p>If tests are not running in the REPL or are returning unexpected errors, a command line test runner is a useful way to diagnose if it is the test code or test tools causing the error.</p> <p>The CLI approach is also more robust for longer running tests than running within an editor.</p> <p>Avoid stale tests</p> <p>Running tests via a command line test runner will never experience stale tests, as long as all relevant changes are saved to the source code files.</p>"},{"location":"testing/unit-testing/#run-tests-in-the-repl","title":"Run tests in the REPL","text":"<p><code>clojure.test</code> includes the <code>run-tests</code> function that runs tests (<code>deftest</code> definitions) in given namespaces and <code>run-all-tests</code> which runs all tests in all namespaces.</p> <pre><code>(run-all-tests)  ; run all tests in all namespaces\n\n(run-tests 'practicalli.system-monitor-test) ; run all tests in practicalli.system-monitor-test\n</code></pre> <p><code>run-tests</code> and <code>run-all-tests</code> are a less common approach as the command line and editor driven test runners provide a rich set of features</p>"},{"location":"testing/unit-testing/#project-structure-with-tests","title":"Project structure with tests","text":"<p>For each source code file in <code>src</code> there should be a corresponding file in <code>test</code> directory with the same name and <code>_test</code> postfix.</p> <p>For example, code to test the <code>src/codewars/rock_paper_scissors.clj</code> is saved in the file <code>src/codewars/rock_paper_scissors_test.clj</code> file.</p> <p></p> <p>Example project: CodeWars: Rock Paper Scissors</p>"},{"location":"testing/unit-testing/#source-and-test-namespaces","title":"Source and Test Namespaces","text":"<p>As with file names, the namespaces for each test code file is the same as the source code it is testing, with a <code>-test</code> postfix.</p> <p><code>codewars/rock-paper-scissors</code> source code namespace will have a matching <code>codewars/rock-paper-scissors-test</code> namespace.</p> Create Projects from templates <p>Templates typically include a parallel <code>test</code> and <code>src</code> directory structure.  The <code>clj-new</code> tool has build it templates (app, lib) and will create <code>src</code> and <code>test</code> directories in the projects it creates.</p> <p><code>clojure -T:project/new :template app :name practicalli/rock-paper-scissors-lizard-spock</code></p>"},{"location":"testing/unit-testing/#project-examples-code-challenges-with-unit-tests","title":"Project Examples: Code challenges with unit tests","text":"<ul> <li>TDD Kata: Recent Song-list - simple tests examples</li> <li>Codewars: Rock Paper Scissors (lizard spock) solution - <code>and</code> examples</li> <li>practicalli/numbers-to-words - overly verbose example, ripe for refactor</li> <li>practicalli/codewars-guides - deps.edn projects</li> <li>practicalli/exercism-clojure-guides - Leiningen projects</li> </ul>"},{"location":"testing/unit-testing/#references","title":"References","text":"<ul> <li>Example based unit testing in Clojure - PurelyFunctional.tv</li> </ul>"},{"location":"testing/unit-testing/clojure-test-expectations/","title":"Clojure test Expectations","text":"<p><code>clojure.test.expectations</code> uses the same tooling as <code>clojure.test</code> and only depends on that library.</p>"},{"location":"testing/unit-testing/clojure-test-expectations/#using-a-depsedn-alias","title":"Using a deps.edn alias","text":"<p> Practicalli Clojure CLI Config</p>"},{"location":"testing/unit-testing/clojure-test-expectations/#add-dependency","title":"Add dependency","text":"<p>Edit the deps.edn file for the current project</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/","title":"Configure Unit Testing for deps.edn projects","text":"<p><code>clojure.test</code> namespace is part of the Clojure standard library, so the Clojure library is the only dependency required in the project.</p> <pre><code>{:deps {org.clojure/clojure {:mvn/version \"1.10.3\"}}}\n</code></pre> <p>Unit tests code should reside under the <code>test</code> directory of a project.  The <code>test</code> directory should not be part of the main classpath, otherwise test classes would be included in the project packaging and deployed to production.</p> <p>Use an alias to add the <code>test</code> directory, either from a user level configuration or the Clojure project <code>deps.edn</code> configuration file.</p> <p>{% tabs practicalli=\"practicalli/clojure-deps-edn\", deps=\"Manual deps.edn projects\" %}</p> <p>{% content \"practicalli\" %}</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#adding-test-path","title":"Adding test path","text":"<p>  Practicalli Clojure CLI Config user-level configuration contains several aliases for Clojure and ClojureScript test runners, each alias includes the <code>test</code> directory as an <code>:extra-path</code>.</p> <p><code>:test/env</code> alias is also provided, which simply adds the <code>test</code> directory to the class path. The <code>:test/env</code> alias is useful in concert with other aliases or for editors that have their own built in test runners (e.g. CIDER).</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#using-kaocha-test-runner","title":"Using kaocha test runner","text":"<p>lambdaisland/kaocha is a fast and comprehensive test runner for Clojure and ClojureScript.</p> <p><code>:test/run</code> alias runs all tests from the source code files, called with the <code>clojure</code> command in the root of the Clojure project.  The alias includes <code>test</code> as an extra path and calls the Kaocha test runner.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Kaocha can also watch for changes saved to file and re-run the tests.</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Both kaocha aliases are configured to stop if a test fails.  When re-running kaocha, only failed tests and tests that have changed are run (including tests where the code they are testing has changed).</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#alias-to-include-the-test-directory","title":"Alias to include the test directory","text":"<p>Add the following aliases to the Clojure CLI tools user wide configuration, (e.g. <code>~/.clojure/deps.edn</code>), or to the project <code>deps.edn</code> file.</p> <p>To use a test runners with a <code>deps.edn</code> projects, the <code>test</code> directory should be on the classpath.</p> <p>practicalli/clojure-deps-edn defines an environment alias to include the test path.</p> <pre><code>:aliases\n{\n  :test/env\n  {:extra-paths [\"test\"]}\n}\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#cognitect-labs-clojure-test-runner","title":"Cognitect labs Clojure test runner","text":"<p><code>:test/cognitect</code> is a simple to use test runner for Clojure projects.</p> <pre><code>clojure -X:test/cognitect\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#kaocha-unit-test-and-clojure-spec-runner","title":"Kaocha unit test and clojure spec runner","text":"<p><code>:test/kaocha</code> alias unit test runner that also supports Clojure Spec functional tests.  the kaocha test runner on the current project.  Add a <code>test.edn</code> file to configure which tests are run by kaocha.</p> <pre><code>clojure -X:test/kaocha\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#references","title":"References","text":"<ul> <li>Practicalli Spacemacs - Unit testing with Cider and Kaocha in Emacs</li> <li>lambdaisland/kaocha is a test runner that supports Clojure CLI, Leiningen and Boot project configuration.</li> <li>Leiningen project configuration for unit testing</li> </ul>"},{"location":"testing/unit-testing/fixtures/","title":"Test Fixtures","text":"<p>Unit tests may require the system to be in a particular state before running a test.  The state may need to be reset after running a test such as a database</p> <p>Fixtures allow you to run code before and after tests, to set up the context in which tests should be run.  Consider when fixtures should be run, especially fixtures that take a noticeable time to setup or tear down.</p> <p>Slow running unit tests lead to unit tests not being run so often and therefore limit their value.</p> <p>Organise tests with test selectors</p> <p>Tests with fixtures may be slower to run so separate them by using a test selector, a piece of meta data attached to a <code>deftest</code> definition. For example, add the <code>^:persistence</code> meta data to test that require database fixtures  (deftest ^:database db-bulk-upload).  The test runner can be instructed to skip or focus on tests with specific meta data.</p>"},{"location":"testing/unit-testing/fixtures/#defining-a-fixture","title":"Defining a fixture","text":"<p>Require the <code>use-fixtures</code> function in the require expression for <code>clojure.test</code></p> <pre><code>(ns domain.application-test\n  (:require [clojure.test :refer [deftest is testing use-fixtures]]))\n</code></pre> <p>A fixture is a standard Clojure function which takes a function as an argument.  The function passed as an argument is either an individual test or all tests in the namespace, depending on how the fixture is used.</p> <pre><code>(defn my-fixture [test-run]\n   ;; Setup: define bindings, create state, etc.\n\n  (test-run) ;; Run the relevant tests for the fixture (see `use-fixtures`)\n\n   ;; Tear-down: reset state to a known value\n )\n</code></pre>"},{"location":"testing/unit-testing/fixtures/#when-to-run-fixtures","title":"When to run fixtures","text":"<p>The <code>use-fixtures</code> function defines when a fixture should be called when running the unit tests in each namespace.  All Clojure unit test runners should support the <code>use-fixtures</code> definitions when running the tests.</p> When Description <code>(use-fixtures :once fixture1 fixture2)</code> Run the fixtures once for the namespace. <code>(use-fixtures :each fixture1 fixture2)</code> Run the fixtures for each <code>deftest</code> in the namespace <p>Once</p> <p>The setup in the fixture is run, followed by all the <code>deftest</code> functions in the namespace, then the fixture tear-down is run.</p> <p>Running a fixture once per namespace is useful for establishing a database connection or creating a particular state of data for all the unit tests to use.</p> <p>Each</p> <p>The fixture setup is run before each <code>deftest</code> function in the namespace. The fixture tear-down is run after each <code>deftest</code> function.</p>"},{"location":"testing/unit-testing/fixtures/#anonymous-function-fixture","title":"Anonymous function fixture","text":"<p>The <code>use-fixtures</code> function can also include anonymous function as well as a namespace scoped functions (<code>deftest</code>).</p> <pre><code>(use-fixtures :each (fn [f] #_setup... (f) #_teardown))\n</code></pre> <p><code>defn</code> functions are usually recommended unless the fixture code is relatively terse.</p> <p>Development database</p> <p>Define a fixture to reset the database before running a test and clear the database after each test.</p> <p>The <code>create-database</code> and <code>delete-database</code> are helper functions that are part of the namespace under test.</p> <pre><code>(defn database-reset-fixture\n  \"Setup: drop all tables, creates new tables\n   Teardown: drop all tables\n  SQL schema code has if clauses to avoid errors running SQL code.\n  Arguments:\n  test-function - a function to run a specific test\"\n  [test-function]\n  (SUT/create-database)\n  (test-function)\n  (SUT/delete-database))\n</code></pre> <p>The fixture should be used for each unit test (<code>deftest</code>) that is defined in the namespace the <code>database-reset-fixture</code> is defined in.</p> <pre><code>(use-fixtures :each database-reset-fixture)\n</code></pre>"},{"location":"testing/unit-testing/fixtures/#references","title":"References","text":"<ul> <li><code>use-fixtures</code> - Clojuredocs.org</li> <li>Kaocha - focusing and skipping</li> <li>Clojure Test Fixtures - astrocaribe</li> </ul>"},{"location":"testing/unit-testing/test-selectors/","title":"Test Selectors","text":"<p>As a project grows in scope its important that tests continue to run quickly.  Test runs which take a noticeable time to complete diminish the motivation to run tests frequently.</p> <p>Divide tests into categories to run selective tests, continuing to provide fast feedback.  Longer running tests can be run less often without loosing quality in the feedback from tests.</p> <p>Test runners use test selectors to run a specific categories, or exclude test selectors so all tests except that category runs.</p> <p>kaocha focus and skipping</p> <p>kaocha can group tests into categories in the <code>tests.edn</code> configuration, providing a way to focus or exclude different types of tests (e.g. <code>:unit</code> and <code>:spec</code>)</p>"},{"location":"testing/unit-testing/test-selectors/#test-category-metadata","title":"Test category metadata","text":"<p>Add metadata to <code>deftest</code> functions to provide categories of tests, e.g. <code>integration</code>, <code>persistence</code>, etc.</p> <pre><code>(deftest ^:integration register-customer\n  (is ,,,))\n</code></pre> <p>Example from Banking on Clojure</p> <pre><code>(deftest ^:persistence new-customer-test\n  (testing \"New customer generative testing\")\n  (is (spec/valid?\n        :customer/id\n        (:customer/id (SUT/new-customer\n                        (spec-gen/generate (spec/gen :customer/unregistered)))))))\n</code></pre>"},{"location":"testing/unit-testing/test-selectors/#test-selectors_1","title":"Test Selectors","text":"<p>Start a test selective category of tests running by specifying test selectors to include or exclude.</p> KaochaSpacemacsCiderCognitect <p>kaocha supports meta data on <code>deftest</code> expressions and has its own metadata tag for skipping tests, <code>^:koacha/skip</code></p> <p>Examples of tests with and without test selectors</p> <pre><code>(deftest simple-test\n  (is (= 1 1)))\n\n(deftest ^:integration system-update-test\n  (is (spec/valid? :system/update (long-running-function))))\n\n(deftest ^:kaocha/skip under-development-test\n  (is (= 3 21/7)))\n</code></pre> <p>Tests with test selector metadata can be skipped using a <code>tests.edn</code> configuration</p> <pre><code>#kaocha/v1\n{:tests [{:kaocha.filter/skip-meta [:integration]}]}\n</code></pre> <p>Running kaocha will only run the <code>simple-test</code>, skipping the other two tests.</p> <p>Specifying <code>--skip-meta</code> on the command line gives the same results</p> <pre><code>bin/kaocha --skip-meta :metadata-name\n</code></pre> <p>Running tests with the universal argument will prompt for test selector filters and only Run those tests that match the selector inclusions/exclusions.</p> <p><code>SPC u , t a</code> runs all tests, prompting for tests selector names to include (space separated)</p> <p></p> <p>Then prompting for the test selectors to exclude.  A warning displays if CIDER does not find the test selector name.</p> <p></p> <p>Invoke the CIDER test runner commands with the universal argument and CIDER will prompt for test selector filters, running only those tests that match the selector inclusions/exclusions.</p> <p><code>C-c C-t p</code> runs all the tests in a project.</p> <p><code>C-u C-c C-t p</code> prompts for test selectors and runs the matching tests in a project.</p> <p><code>C-c C-t l</code> runs all tests currently evaluated in the REPL.</p> <p><code>C-u C-c C-t l</code> prompts for test selectors and runs the matching tests currently evaluated in the REPL.</p> <p>CIDER first prompts for the test selectors to include:</p> <p></p> <p>Then prompts for the test selectors to exclude.  A warning displays if CIDER does not find the test selector name.</p> <p></p> <p>The Cognitect Labs test runner uses command line options to specify test selectors, <code>--include</code> and <code>--exclude</code>.</p> <p>  Practicalli Clojure CLI Config configuration provides the <code>:test/congnitect</code> alias.</p> <p><code>clojure -M:test/cognitect --include :database</code> only runs tests with the <code>^:database</code> test selector</p> <p><code>clojure -M:test/cognitect --exclude :integration</code> runs all tests except those with the <code>^:integration</code> test selector</p>"},{"location":"testing/unit-testing/test-selectors/#references","title":"References","text":"<ul> <li>Kaocha - Focus and skipping tests with test selectors</li> <li>Convoluted Magic of Leiningen Test Selectors</li> <li>How to use Leiningen test selectors to filter by test name</li> <li>Stack overflow - Lein test with Selectors - how to specify a test for multiple conditions</li> </ul>"},{"location":"testing/unit-testing/writing-unit-tests/","title":"Writing Unit Tests with clojure.test","text":"<p>Unit tests are centered on assertions, testing if something returns a true or false value.</p> <p><code>is</code> function is the simplest assertion and the most common.  It checks to see if an expression given is true and if so then the assertion passes.  If the value is false then that assertion fails.</p> <p><code>as</code> provides a way to run the same assertion with different values, testing the same function with a collection of arguments.  This provides a clean way to test a function without lots of repetition.</p> <p><code>testing</code> is a macro to group multiple assertions together, providing a string in which to describe the context the assertions are testing.  The well worded context string is invaluable for narrowing down on which assertions are failing.</p> <p><code>deftest</code> is a collection of assertions, with or without <code>testing</code> expressions.  The name of the deftest should be the name of the function it is testing with <code>-test</code> as a postfix.  For example, the function <code>practicalli.playground/calculator</code> would have a <code>deftest</code> called <code>practicalli.playground-test/calculator-test</code></p>"},{"location":"testing/unit-testing/writing-unit-tests/#requiring-namespaces","title":"Requiring Namespaces","text":"<p>A test namespace has a singular purpose to test a matching src namespace.</p> <p>The idiomatic approach is to <code>:refer</code> specific functions from <code>clojure.test</code> as those functions are used.</p> <p>The namespace to be tested is referred using a meaningful alias. The alias highlight the exact functions being tested in the body of the code.  This provides a visual way to separate functions under test with other test functions, especially if there are helper functions or vars used for test data.</p> REPLproject <p><pre><code>(require '[clojure.test :refer [are deftest is testing]])\n</code></pre> The namespace under test should be referred using the alias so they are readily identified within the test code. <pre><code>(require '[practicalli.gameboard.spec :as gameboard-spec])\n</code></pre></p> <p>Add <code>clojure.test</code> to the namespace definition along with the namespace under test. <pre><code>(ns practicalli.app-namespace-test\n  (:require '[clojure.test :refer [are deftest is testing]]\n             [practicalli.gameboard.spec :as gameboard-spec]))\n</code></pre></p>"},{"location":"testing/unit-testing/writing-unit-tests/#simple-example","title":"Simple Example","text":"<pre><code>(deftest public-function-in-namespace-test\n  (testing \"A description of the test\"\n    (is (= 1 (public-function arg)))\n    (is (predicate-function? arg))))\n</code></pre>"},{"location":"testing/unit-testing/writing-unit-tests/#assertion-data-set","title":"Assertion data set","text":"<p>The <code>are</code> macro can also be used to define assertions, especially when there would otherwise be multiple assertions that only differ by their test data.</p> <p>An <code>are</code> assertion defines the arguments to the test, the logic of the test and a series of test data.</p> <pre><code>(are [x y] (= x y)\n              2 (+ 1 1)\n              4 (* 2 2))\n</code></pre> <p>This is equivalent to writing</p> <pre><code>         (do (is (= 2 (+ 1 1)))\n             (is (= 4 (* 2 2))))\n</code></pre> <p>Refactor test assertion to use data set</p> <p>Assertions in the test take the same shape of values, so are candidates to refactor to the <code>are</code> macro. <pre><code>(deftest encoder-test\n  (testing \"Tens to number words\"\n    (is (= '(\"zero\" \"ten\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\1 \\0))))\n    (is (= '(\"zero\" \"eleven\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\1 \\1))))\n    (is (= '(\"zero\" \"twenty\" \"zero\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\2 \\0))))\n    (is (= '(\"zero\" \"twenty\"\"one\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\2 \\1))))\n    (is (= '(\"zero\" \"forty\" \"two\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\4 \\2))))))\n</code></pre> Refactor the assertions using are simplifies the code, making it simpler to change further and extend with more data. <pre><code>(deftest encoder-test\n  (testing \"Tens to number words\"\n    (are [words numbers]\n      (= words (character-sequence-&gt;word-sequence dictionary/digit-&gt;word numbers))\n        '(\"zero\" \"ten\")           '(\\0 \\1 \\0)\n        '(\"zero\" \"eleven\")        '(\\0 \\1 \\1)\n        '(\"zero\" \"twenty\" \"zero\") '(\\0 \\2 \\0)\n        '(\"zero\" \"twenty\"\"one\")   '(\\0 \\2 \\1)\n        '(\"zero\" \"forty\" \"two\")   '(\\0 \\4 \\2)))\n</code></pre></p> <p>Generative Testing provides a wide range of values</p> <p>Generating test data from Clojure Specs provides an extensive set of values that provide an effective way to test functions.</p>"},{"location":"testing/unit-testing/writing-unit-tests/#reference","title":"Reference","text":"<p>clojure.test API</p>"},{"location":"testing/unit-testing/writing-unit-tests/#code-challenges-with-tests","title":"Code challenges with tests","text":"<p>TDD Kata: Recent Song-list TDD Kata: Numbers in words Codewars: Rock Paper Scissors (lizard spock) solution practicalli/codewars-guides practicalli/exercism-clojure-guides</p>"},{"location":"thinking-functionally/","title":"Thinking Functionally","text":"<p>In this section I cover some simple examples of Clojure code to help you think about the concepts involved in functional programming.</p> <p>An overview of thinking functionally is also covered in the presentation entitled Getting into Functional Programming with Clojure on slideshare and its accompanying youtube video</p> Get into Functional Programming with Clojure  from John Stevenson <p></p> <p>Get a free Clojurians slack community account</p>"},{"location":"thinking-functionally/arity/","title":"Arity","text":"<p>Fixme work in progress</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/","title":"Example: Hitchhikers Guide","text":"<p>This is an example of using the threading macros and  a REPL to give fast feedback as you are developing code.</p> <p>Suggest you use the assumed perfectly legal copy of the Hitch-hickers book text using the <code>slurp</code> function</p> <p>Approximate algorithm</p> <ul> <li>Use a regular expression to create a collection of individual words - eg. #\"[a-zA-Z0-9|']+\"</li> <li>Convert all the words to lower case so they match with common words source - <code>clojure.string/lower-case</code></li> <li><code>Remove</code> the common English words used in the book, leaving more context specific words</li> <li>Calculate the <code>frequencies</code> of the remaining words, returning a map of word &amp; word count pairs</li> <li><code>Sort-by</code> word count values in the map</li> <li><code>Reverse</code> the collection so the most commonly used word is the first element in the map</li> </ul> <pre><code>(def book (slurp \"http://clearwhitelight.org/hitch/hhgttg.txt\"))\n\n(def common-english-words\n  (-&gt; (slurp \"https://www.textfixer.com/tutorials/common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n\n;; using a function to pull in any book\n(defn get-book [book-url]\n  (slurp book-url))\n\n\n(defn -main [book-url]\n  (-&gt;&gt; (get-book book-url)\n       (re-seq #\"[a-zA-Z0-9|']+\")\n       (map #(clojure.string/lower-case %))\n       (remove common-english-words)\n       frequencies\n       (sort-by val)\n       reverse))\n\n;; Call the program\n\n(-main \"http://clearwhitelight.org/hitch/hhgttg.txt\")\n</code></pre>"},{"location":"thinking-functionally/example-hitchhikers-guide/#note","title":"NOTE","text":"<p>Write functions that will give a list of the most used words used in a book, excluding the common English words like \"the, and, it, I\".  Join those functions with a threading macro.</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/#deconstructing-the-code-in-the-repl","title":"Deconstructing the code in the repl","text":"<p>To understand what each of the functions do in the <code>-main</code> function then you can simply comment out one or more expressions using in front of the expression #_</p> <pre><code>(defn -main [book-url]\n  (-&gt;&gt; (get-book book-url)\n       #_(re-seq #\"[a-zA-Z0-9|']+\")\n       #_(map #(clojure.string/lower-case %))\n       #_(remove common-english-words)\n       #_frequencies\n       #_(sort-by val)\n       #_reverse))\n</code></pre> <p>Now the <code>-main</code> function will only return the result of the <code>(get-book book-url)</code> function.  To see what each of the other lines do, simply remove the #_ character from the front of an expression and re-evaluate the <code>-main</code> function in the repl</p> <p>Hint In Spacemacs / Emacs, the keybinding C-c C-p show the output in a separate buffer.  Very useful when the function returns a large results set.</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/#off-line-sources-of-hitch-hickers-book-and-common-english-words","title":"Off-line sources of Hitch-hickers book and common English words","text":"<pre><code>(def book (slurp \"./hhgttg.txt\"))\n\n(def common-english-words\n  (-&gt; (slurp \"common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre> <p>Original concept from Misophistful: Understanding thread macros in clojure</p> <p>Hint The <code>slurp</code> function holds the contents of the whole file in memory, so it may not be appropriate for very large files.  If you are dealing with a large file, consider wrapping slurp in a lazy evaluation or use Java IO (eg. <code>java.io.BufferedReader</code>, <code>java.io.FileReader.</code>).  See the Clojure I/O cookbook and The Ins &amp; Outs of Clojure for examples.</p>"},{"location":"thinking-functionally/first-class-functions/","title":"First Class functions","text":"<p>Idempotent - given the same input you get the same output</p> <pre><code>(+ 1 2 3 4 5 6 7 8 9 10)\n</code></pre> <p>The <code>range</code> function generates a sequence of numbers and when given arguments it does so from a specific range.  The second number is exclusive, so for 1 to 10 the second argument should be 11.</p> <pre><code>(range 1 11)\n</code></pre> <p>Unfortunately we cant just add the result of a range, because it returns a lazy sequence  So <code>(range)</code> by itself will create an error</p> <pre><code>(+ 1 (range 1 11))\n</code></pre> <p>Using a function called <code>reduce</code> we can calculate a single total value from all the numbers in the collection.</p> <p>The reduce function take 2 arguments, the first is the function to apply to a data structure, the second is the data structure.</p> <pre><code>(reduce + (range 1 11))\n\n(reduce + (1 2 3 4 5 6 7 8 9 10))\n</code></pre>"},{"location":"thinking-functionally/first-class-functions/#note","title":"Note::","text":"<p>Write an expression to add up the numbers from 1 to 10 and return the overall total.</p>"},{"location":"thinking-functionally/first-class-functions/#note_1","title":"Note::","text":"<p>Create an expression to do the same calculation, but without having to write all the numbers.  Hint: consider the functions called range and reduce.</p>"},{"location":"thinking-functionally/function-composition/","title":"Function Composition","text":"<p>We have discussed how functional programs are essentially a number of functions that work together, this is called composition (functional composition).</p> <pre><code>(let [calculated-value (* 10 (reduce +  (map inc (range 5))))]\n  calculated-value)\n</code></pre> <p>This expression is common in the Lisp &amp; Clojure languages.  Occasionally the created expressions can becomes challenging to read.  To overcome this parsing complexity, developers often break down a more complex expression into its parts, extracting code into its own function.</p> <p>Note Brake down the above example into each expression that gives a value</p> <pre><code>(range 5)\n\n(map inc (range 5))\n\n(reduce +  (map inc (range 5)))\n\n(* 10 (reduce +  (map inc (range 5))))\n\n\n;; Additional examples\n\n;; Use a let expression for code that is used more than once in a function\n\n(let [calculated-value (* 10 (reduce +  (map inc (range 5))))]\n  calculated-value)\n\n;; Use defn to define a function for code that multiple functions will call\n;; and generalise the function with arguments\n\n(defn common-data-calculation\n  [certainty-factor scope]\n  (* certainty-factor (reduce +  (map inc (range scope)))))\n</code></pre>"},{"location":"thinking-functionally/functors/","title":"Functors","text":"<p>Fixme work in progress</p> <p>Put simply, a function that takes a value and a function as its arguments, eg <code>map</code>.  The argument pass as a value is most commonly a collection type (vector, map, string, list).</p> <p>From Wikipedia</p> <p>In mathematics, a functor is a type of mapping between categories which is applied in category theory. Functors can be thought of as homomorphisms between categories. In the category of small categories, functors can be thought of more generally as morphisms.</p> <p>A functor applies the given function to each element in the the collection by unpacking and each element from the collection and passing it to the function as an argument.  The result from each application of the function from the element of the collection is put into a new collection.  This new collection is returned once all elements of the original collection have been processed.</p> <p>The function, eg. + is applied in turn to each value and returns a structured value as a result, eg. a list or vector</p> <pre><code>(map inc [1 2 3 4 5])\n\n(inc 1 )\n</code></pre>"},{"location":"thinking-functionally/higher-order-functions/","title":"Higher Order functions","text":"<p>Functions can be used as an arguments to other functions as we have seen in function composition.  This is possible because a function always evaluates to a value.  This is the basis of function composition.</p> <p>Higher Order functions can also return a function definition, as when that function definition is evaluated it to will return a value.</p> <p>You could have a function that returns a function definition which in turn returns a function definition, but at some point this will get very confusing for the developers (yes, that means you).</p> <pre><code>(filter\n even?\n (range 1 10))\n</code></pre> <pre><code>(defn twice [f]\n  ,,,)\n</code></pre> <pre><code>;; Our higher order function\n\n(defn twice [function x]\n  (function (function x)))\n\n(twice\n  (fn [arg]\n    (* 3.14 arg))\n  21)\n;; =&gt; 207.0516\n\n;; using the short syntax for a function definition\n\n(twice #(+ 3.14 %) 21)\n;; =&gt; 207.0516\n</code></pre> <pre><code>(defn calculation [f]\n  ,,,)\n</code></pre> <pre><code>(defn calculation [f]\n  (fn [&amp; args]\n    (reduce f args)))\n\n((calculation +) 1 1 2 3 5 8 13)\n\n;; The result of `(calculation +)` is also in a list,\n;; so it will be called as a function, with the arguments 1 1 2 3 5 8 13\n</code></pre>"},{"location":"thinking-functionally/higher-order-functions/#notereturn-the-even-numbers-from-1-to-10","title":"Note::Return the even numbers from 1 to 10","text":"<p>Generate a range of numbers from 1 to 10</p> <p>Use a function that checks if a number is even and filter the range of numbers to return only the numbers that match</p>"},{"location":"thinking-functionally/higher-order-functions/#notecreate-a-named-function-as-a-higher-order-function-called-twice","title":"Note::Create a named function as a higher order function called <code>twice</code>","text":"<p>The function twice which takes a function and value as arguments.</p> <p>The twice function should call the function passed as an argument on the value passed as an argument.</p> <p>The result should be then used as an argument to calling the function passed as an argument again.</p> <p>Call the twice function with an inline function which takes a number as an argument and adds it to Pi, <code>3.14</code>.</p>"},{"location":"thinking-functionally/higher-order-functions/#notedefine-a-function-that-returns-a-function","title":"Note::Define a function that returns a function","text":"<p>The function should take a clojure.core function for a mathematical calculation, i.e. <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code></p> <p>The returning function should take one or more arguments <code>[&amp; args]</code> and use the function originally passed as an argument to <code>reduce</code> the data to a single value.</p>"},{"location":"thinking-functionally/higher-order-functions/#references","title":"References","text":"<ul> <li>Writing Elegant Clojure code using Higher Order functions</li> </ul>"},{"location":"thinking-functionally/homoiconicity/","title":"Homoiconicity","text":"<p>Clojure is a homoiconic language, which is a term describing the fact that Clojure programs are represented by Clojure data structures.</p> <p>In Clojure you write your business logic as functions.  A function is defined using a list structure.  A function is called using a list structure, as the first element of a list is evaluated as a function call.</p> <p>Hint Everything in Clojure is a List (or vector, map, set).</p> <p>This is a very important difference between Clojure (and Common Lisp) and most other programming languages - Clojure is defined in terms of the evaluation of data structures and not in terms of the syntax of character streams/files.</p> <p>It is quite easy for Clojure programs to manipulate, transform and produce other Clojure programs.  This is essentially what macros do in Clojure, they re-write Clojure for you.</p> <p>Hint If you were going to create Skynet, it would be so much easier to do in Clojure</p> <p></p>"},{"location":"thinking-functionally/homoiconicity/#an-example","title":"An example","text":"<p>Consider the following expression:</p> <pre><code>(let [x 1] \n    (inc x))\n</code></pre> <p>Evaluating the above code in the REPL returns <code>2</code> because the repl compiles and executes any code entered into it. But <code>[x 1]</code> is also a literal vector data structure when it appears in a different context.</p> <p>All Clojure code can be interpreted as data in this way. In fact, Clojure is a superset of EDN \u2013 Extensible Data Notation, a data transfer format similar to JSON. EDN supports numbers, strings, lists (1 2 3), vectors [1 2 3], maps {\"key\" \"value\"}.</p> <p>If this sounds and looks a lot like Clojure syntax, it\u2019s because it is. The relationship between Clojure and EDN is similar to that of Javascript and JSON, but much more powerful.</p> <p>In Clojure, unlike JavaScript, all code is written in this data format. We can look at our let statement not as Clojure code, but an EDN data structure. Let\u2019s take a closer look:</p> <pre><code>(let [x 1] \n    (inc x))\n</code></pre> <p>In this data structure, there are four different types of data.</p> <ul> <li>1 is a literal integer.</li> <li>let, x, and inc are symbols. A symbol is an object representing a name \u2013 think a string, but as an atomic object and not a sequence of characters.</li> <li>[x 1] is a vector containing two elements: symbol, x, and an integer, 1. Square brackets always signify vectors when talking about EDN data structures.</li> <li>(inc x) is a list (a linked list data structure) containing two symbols, inc and x.</li> </ul> <p>When thinking about a piece of Clojure code as a data structure, we say we are talking about the form. Clojure programmers don\u2019t normally talk about EDN, there are just two ways to think about any bit of Clojure: 1) as code that will execute or 2) as a form, a data structure composed of numbers, symbols, keywords, strings, vectors, lists, maps, etc.</p> <p>Symbols are particularly important. They are first class names. In Clojure, we distinguish between a variable and the name of that variable. When our code is executing, x refers to the variable established by our let binding. But when we deal with that code as a form, x is just a piece of data, it\u2019s a name, which in Clojure is called a symbol.</p> <p>This is why Clojure is homoiconic. Code forms are data structures and data structures can be thought of as forms and executed as code. This transformation is quite literal, and two core operations, quote and eval are key ingredients to this potion.</p>"},{"location":"thinking-functionally/homoiconicity/#references","title":"References","text":"<ul> <li>The Reader - Clojure. org</li> <li>Homoiconicity - Wikipedia</li> <li>Is Clojure Homoiconic - muhuk.com</li> <li>Understanding Homoiconicity in Clojure - Drew Colthorp</li> </ul>"},{"location":"thinking-functionally/immutability/","title":"Immutability","text":"<p>There is a strong emphasis on immutability in Clojure.  Rather than create variables that change, Clojure uses values that do not change.</p> <p>Values in Clojure include numbers, characters, strings.</p> <p>When functions act on values, a new value is created and returned, rather than modifying the existing value.</p> <p>TODO include a diagram to visualise this...</p>"},{"location":"thinking-functionally/immutability/#immutabile-data-structures","title":"Immutabile data structures","text":"<p>List, Map, Vector and Set are all immutable data structures in Clojure.</p> <p>So when you use these data structures with a function, a new data structure is returned.</p> <p>Hint When a new data structure is created from an existing data structure, then under the covers the two data structures actually share memory use for any elements that are common.  This keeps copies very cheap to create in terms of memory used.</p> <p>See the section on data structures for more details.</p>"},{"location":"thinking-functionally/immutable-collections/","title":"Immutable collections","text":"<p>As we have discussed, immutable data structures cannot be changed.  So when you run a function over a collection a copy of that collection is returned.  Lets see this by running some code in the REPL.</p> <p>Note Define a data structure called <code>numbers</code> using a vector.  Then write a function that uses the <code>map</code> and <code>inc</code> function to increment all the numbers in a vector.</p> <p>Then check the current value of the <code>numbers</code> data structure by evaluating its name.</p> <pre><code>;; define the data structure \n(defn numbers [1 2 3 4 5])\n\n;; increment the numbers\n(map inc numbers)\n\n;; see the current value of numbers\nnumbers\n</code></pre> <p>Note Use the <code>conj</code> function to first add the number <code>5</code> to the <code>numbers</code> vector from the previous exercise and check the value of <code>numbers</code>.  Then add the number <code>6</code> to the <code>numbers</code> vector and check the value of <code>numbers</code>.</p> <p>Finally, use the <code>conj</code> function to add both <code>5</code> and <code>6</code> to the <code>numbers</code> vector and check the value of <code>numbers</code></p> <pre><code>(def numbers [1 2 3 4])\n\n;; add 5 to the numbers vector\n(conj numbers 5)\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n\n;; add 6 to the numbers vector\n(conj numbers 6)\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n\n;; add 5 and 6 to the numbers vector\n(conj numbers 5 6)\n\n;; Alternatively, you can use the threading macro to chain two conj function calls\n(-&gt; numbers\n    (conj 5)\n    (conj 6))\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n</code></pre> <p>So even though we have applied several functions on the <code>numbers</code> data structure it still has the same value.</p>"},{"location":"thinking-functionally/immutable-local-bindings/","title":"Immutable Local Bindings","text":"<p>Names can be bound to values &amp; and data structures with either the <code>def</code> or <code>let</code> function.  The <code>def</code> binding is global to the namespace, however the <code>let</code> function is local to its use.</p> <p>Hint The <code>let</code> function is typically used to define names within a function definition, or in snippets of code created during repl driven development.</p> <pre><code>(let [five 5]\n  (str \"Within the let expression the value is \" five))\n;; =&gt; Within the let expression the value is 5\n\n;; evaluating the name five outside the let expression returns an error\nfive\n;; =&gt; Unable to resolve symbol: five in this context\n</code></pre> <p>Note Create a local binding called number that represents the value 5 using the <code>let</code> function. Increment the number, then print out the value of number.</p> <pre><code>(let [number 5]\n   (inc number)\n   (str \"The number is still \" number))\n</code></pre> <p>So the value that any local binding points to is immutable too.</p>"},{"location":"thinking-functionally/immutable-values/","title":"Immutable values","text":"<p>Fixme work in progress</p> <p>Values in Clojure include numbers, characters and strings.  When you use functions on these values they do not change, instead a new value is returned.</p> <p>Lets look at a simple example with a number:</p> <pre><code>(def two-little-ducks 22)\n\n(inc two-little-ducks)\n;; =&gt; 23\n\ntwo-little-ducks\n;; =&gt; 22\n</code></pre> <p>Another example with a string:</p> <pre><code>(def message \"Strings are immutable\")\n\n(str message \",\" \" \" \"you cant change them\")\n;; =&gt; \"Strings are immutable, you cant change them\"\n\nmessage\n;; =&gt; \"Strings are immutable\"\n</code></pre> <p>Fixme Add an exercise</p>"},{"location":"thinking-functionally/impure-functions/","title":"Impure functions","text":"<p>We have seen some simple examples of pure functions, so lets see impure functions as a comparison.</p> <pre><code>(def global-value '(5 4 3 2 1))\n\n(defn impure-increment-numbers [number-collection]\n  (map inc global-value))\n\n(impure-increment-numbers '(1 2 3 4 5))\n</code></pre> <p>The above function is using a global value rather than the argument passed makes this function deterministic</p>"},{"location":"thinking-functionally/impure-functions/#side-effect-printing-to-the-console-log","title":"Side Effect: Printing to the console log","text":"<p>Although the following example is probably quite harmless, it is a simple example of a function effecting the state of something outside.  These side effects should be avoided where possible to keep your code simpler to reason about.</p> <pre><code>(defn print-to-console [value-to-print]\n  (println \"The value is:\" value-to-print))\n\n(print-to-console \"a side effect\")\n</code></pre>"},{"location":"thinking-functionally/impure-functions/#side-causes-calling-libraries","title":"Side Causes: Calling libraries","text":"<p>To demonstrate a side causes form of impure functions, lets create a task-comple function that marks a current task complete using the current timestamp.</p> <pre><code>(defn task-complete [task-name]\n  (str \"Setting task \" task-name \" completed on \" (js/Date)))\n\n(task-complete \"hack clojure\")\n</code></pre> <pre><code>(:import java.util.Date)\n\n(defn task-complete [task-name]\n  (str \"Setting task \" task-name \" completed on \" (java.util.Date.)))\n\n(task-complete \"hack clojure\")\n</code></pre> <p>In this example we have called to the outside world to generate a value for us.  The above example is fairly simple, however by calling the outside world rather than passing in a date it makes the functions purpose far less clear.</p>"},{"location":"thinking-functionally/impure-functions/#hint-the-function-javautildate-is-actually-a-call-to-instantiate-a-javautildate-object-the-full-stop-character-at-the-end-of-the-name-makes-it-a-function-call-and-is-the-short-form-of-new-javautildate","title":"Hint:: The function <code>(java.util.Date.)</code> is actually a call to instantiate a java.util.Date object.  The full-stop character at the end of the name makes it a function call and is the short form of <code>(new java.util.Date)</code>","text":""},{"location":"thinking-functionally/impure-functions/#re-write-as-a-pure-function","title":"Re-write as a pure function","text":"<p>Change the task-complete function definition and function call to take both the task-name and completed-date as arguments.</p> <pre><code>(defn task-complete [task-name completed-date]\n  (str \"Setting task \" task-name \" completed on \" completed-date))\n\n(task-complete \"hack clojure\" (js/Date))\n</code></pre> <p>Required values should be generated outside a function where possible.  In this case in the <code>(js/Date)</code> function is first evaluated and replaced by its value, then that date value is passed to the function as an argument, keeping the function pure.</p> <p>The pure version of the function in Clojure, using the java.util.Date function.</p> <pre><code>(:import java.util.Date)\n\n(defn task-complete [task-name completed-date]\n  (str \"Setting task \" task-name \" completed on \" completed-date))\n\n(task-complete \"hack clojure\" (java.util.Date.))\n</code></pre>"},{"location":"thinking-functionally/iterate-over-values/","title":"iterate Over Values","text":"<p>This</p> <ul> <li>loop recur</li> <li>reducing functions</li> <li>map apply reduce</li> <li>partition group-by sort-by</li> </ul>"},{"location":"thinking-functionally/iterate-over-values/#hintwork-in-progress","title":"Hint::Work in progress","text":""},{"location":"thinking-functionally/iterate-over-values/#loop-recur","title":"loop recur","text":"<p>loop recur is a very detailed way of defining a way to iterate over values. map, reduce and apply are commonly used abstractions for iterating over values. They simplify the code (once you are comfortable with them)</p> <p>Functions that iterate over values usually treat a string as a sequence of characters.</p>"},{"location":"thinking-functionally/lazy-evaluation/","title":"Lazy Evaluation","text":"<p>Fixme work in progress</p> <p>In the most basic way possible, laziness is the ability to evaluate an expression only when it's actually needed.  Taken further, laziness is also evaluating an expression only to the extent required.</p>"},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-definition","title":"Laziness in definition","text":""},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-evaluation","title":"Laziness in evaluation","text":""},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-partial-evaluation","title":"Laziness in partial evaluation","text":"<p>Clojure is not entirely lazy, only the majority of sequence operations like map, reduce, filter or repeatedly are lazy evaluated.</p> <p>The most common use of laziness are infinite lists or streams. For example, we could define a list of all prime numbers. In case you didn't know, that's a lot of prime numbers (infinitely many).</p> <p>If we would define such list in a language like C++ or Python then the language would try to calculate all prime numbers immediately, which would run literally forever.</p> <p>If we define such list in Haskell or Clojure, then nothing is calculated just yet. As a matter of fact we could happily print out the first 1000 prime numbers from that list without running into a problem. Again, because lazy evaluation only calculates what is really needed, and nothing more.</p>"},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-number-calculation-ratio-type","title":"Laziness in number calculation - Ratio type","text":"<p>Dividing an integer value by another results in a Ratio type if the result would otherwise result in a decimal number.  Clojure only partially evaluates this expression.</p> <pre><code>(/ 22 7)\n</code></pre> <p>We can also just express a value as a ratio.  This works because of the prefix notation of Clojure</p> <pre><code>22/7\n</code></pre> <p>The laziness can be overridden by specifying a precision, eg coercing the result into a specific type</p> <pre><code>(/  22 7.0)\n(double (/ 22 7))\n(float (/ 22 7))\n</code></pre>"},{"location":"thinking-functionally/lazy-evaluation/#making-something-lazy","title":"Making something lazy","text":"<p>The <code>range</code> function returns a sequence of numbers limited by any arguments given when calling the range function.</p> <p>Calling the range function without arguments will force an infinite sequence of numbers to be generated, quickly resulting in an out of memory error in the heap.</p> <p>Instead, we can either pass arguments to the range function that limit the sequence size or wrap the range function in another function</p> <pre><code>(take 7 (range))\n</code></pre> <p>The <code>take</code> function defines how much of a sequence that <code>range</code> should generate.  So we can call range without arguments and it will generate only those numbers in the sequence as specified by <code>take</code>.</p>"},{"location":"thinking-functionally/lazy-evaluation/#references","title":"References","text":"<ul> <li>Being lazy in Clojure - lazily generating monsters</li> </ul>"},{"location":"thinking-functionally/list-comprehension/","title":"List Comprehension","text":"<p>In general terms, list comprehensions should:</p> <ul> <li>be distinct from (nested) for loops and the use of map &amp; filter functions within the syntax of the language.</li> <li>return either a list or an iterator (an iterating being something that returns successive members of a collection, in order),</li> </ul> <p>In Clojure, list comprehension is via the <code>for</code> function.  This is different to the for in other languages as you will see.</p> <pre><code>(for [number [1 2 3]] (* number 2))\n</code></pre> <p>The <code>for</code> function should be read as follows:</p> <p>\"for each number in the collection [1 2 3], apply the function (* number 2)\"</p> <p>Couldn't we just do this with map?  Yes, we could.</p> <pre><code>(map #(* % 2) [1 2 3])\n</code></pre> <p>So why do we need <code>for</code> function?  It really shows its value when you are working with multiple collections</p> <pre><code>(for [number [1 2 3]\n      letter [:a :b :c]]\n  (str number letter))\n</code></pre> <p>Again we could use <code>map</code> function for this as follows</p> <pre><code>(mapcat (fn [number] (map (fn [letter] (str number letter)))))\n</code></pre> <p>So with the <code>for</code> function we can do the same calculation with much easier code to reason about.</p>"},{"location":"thinking-functionally/list-comprehension/#filtering-results-with-predicates","title":"Filtering results with predicates","text":"<p>With the <code>for</code> function we can add a filter on the results by using a predicate, to test if a condition is true or false.  Any values that meet the condition as true are returned, values that are false are omitted.</p> <pre><code>(for [x (range 10) :when (odd? x)] x)\n\n(for [x (range 10) :while (even? x)] x)\n</code></pre> <p>To do this kind of filtering with maps would be possible, however the code would be harder for humans to parse and understand.</p> <p>Note Create a 3-tumbler combination padlock, with each tumbler having a range of 0 to 9. Count the number of possible combinations.  Then add a predicate that filters out some of the combinations</p> <p>Lets just model all the possible combinations</p> <pre><code>(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)]\n [tumbler-1 tumbler-2 tumbler-3])\n</code></pre> <p>Now lets count the combinations</p> <pre><code>(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)]\n         [tumbler-1 tumbler-2 tumbler-3]))\n</code></pre> <p>Now add a predicate using <code>:when</code> to filter out the combinations that do not match.</p> <pre><code>(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)\n             :when (or (= tumbler-1 tumbler-2)\n                       (= tumbler-2 tumbler-3)\n                       (= tumbler-3 tumbler-1))]\n         [tumbler-1 tumbler-2 tumbler-3]))\n</code></pre> <p>Note Create a 2 character prefix for tickets, using capital letters from the English alphabet.  However, exclude I and O as they can be mistaken for numbers</p> <p>Lets just model all the possible combinations</p> <pre><code>(for [letter-1 capital-letters\n      letter-2 capital-letters\n      :when (and (not (blacklisted letter-1))\n                 (not (blacklisted letter-2)))]\n  (str letter-1 letter-2))\n</code></pre>"},{"location":"thinking-functionally/managing-state-changes/","title":"Managing state changes","text":""},{"location":"thinking-functionally/map-with-partial/","title":"map with partial","text":"<p>Lets look at different ways we can map functions over collections with <code>partial</code></p> <p>We can map over a collection of words and increment them by writing an anonymous function.</p> <pre><code>(map (fn [animal] (str animal \"s\")) [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre> <p>The anonymous function has a terse form, that removes the boiler plate function definition <code>(fn [])</code>, allowing definition of only the body of a function.</p> <p><code>%</code> represents a single argument passed to the function.  The <code>%</code> syntax also supports numbers where there are multiple arguments, e.g. <code>%1</code>, <code>%2</code> for the first and second arguments.  <code>%&amp;</code> represents all other arguments and is the same as <code>(fn [&amp; args])</code> or <code>(fn [arg1 &amp; args])</code>.</p> <p>The <code>#</code> character tells the Clojure reader that this is the macro form of a function definition and expands the code to the full form before executing.</p> <pre><code>(map #(str % \"s\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre>"},{"location":"thinking-functionally/map-with-partial/#hintwhen-to-use-the-terse-form-of-anonymous-function","title":"Hint::When to use the terse form of anonymous function","text":"<p>The terse form is often used with higher order functions, as an argument to a function. If the body of the function is simple to comprehend, then the terse form of anonymous function definition is appropriate.  When the body of a function is more complex, then consider using a separate <code>defn</code> function definition.</p>"},{"location":"thinking-functionally/map-with-partial/#returning-a-vector-instead-of-a-sequence","title":"Returning a Vector instead of a sequence","text":"<p>The <code>map</code> function returns a lazy sequence. This is very useful for large data sets.</p> <p><code>mapv</code> is an eager version of map that returns the result as a vector.  This is useful when you require random access lookup in real time.  <code>mapv</code> can also be used to return an eager result if laziness is not required.</p> <pre><code>(mapv #(str % \"s\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre>"},{"location":"thinking-functionally/map-with-partial/#hintlists-and-vectors-does-it-matter","title":"Hint::Lists and vectors - does it matter?","text":"<p>Some functions in <code>clojure.core</code> will return a sequence using the list syntax, even if the arguments given are vectors.  Most of the time this is not important, as Clojure considers values rather than constructs for most of its functions. For example, <code>(= (\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])</code> is true as the values are compared rather than the type of container (list, vector)</p>"},{"location":"thinking-functionally/map-with-partial/#using-conditionals","title":"Using conditionals","text":"<p>Adding sheep as an element raises a problem, as the plural of sheep is sheep.</p> <p>Using a conditional, a test can be added to determine if a name should be made plural</p> <p>First lets abstract out the anonymous function to a shared function using <code>defn</code></p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (str string \"s\"))\n</code></pre> <p><code>def</code> will bind a name to our collection of animals</p> <pre><code>(def animals [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n\n(map pluralise animals)\n</code></pre> <p>The <code>if</code> function included a conditional test.  If that test is true the next expression is evaluated.  If the test is false, the second expression is evaluated.</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (if (= animal \"sheep\")\n    animal\n    (str animal \"s\")))\n\n(map pluralise animals)\n</code></pre> <p>There are several animals that do not have a plural form.  Rather than make a complicated test, a collection of animals that are not plural can be defined.</p> <pre><code>(def non-plural-words [\"deer\" \"sheep\" \"shrimp\" ])\n\n(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n\n(def animals [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\" \"sheep\" \"shrimp\" \"deer\"])\n\n(map pluralise animals)\n</code></pre> <p>To keep the function pure, we should pass the non-plural-words as an argument</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal non-plural-words]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n</code></pre> <p>Using the terse form of the anonymous function, <code>#()</code>, call the pluralise function with two arguments.  <code>map</code> will replace the <code>%</code> character with an element from the animals collection for each element in the collection.</p> <pre><code>(map #(pluralise % non-plural-words) animals)\n</code></pre> <p>The <code>partial</code> function can be used instead of creating an anonymous function, removing the need for more custom code.  The order of the arguments must be swapped for <code>partial</code> to call <code>pluralise</code> correctly</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [non-plural-words animal]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n</code></pre> <p>Now we can call pluralise by wrapping it as a partial function.</p> <p>The argument that is the non-plural-words is constant, its the individual elements of animals I want to get out via map.  So when map runs it gets an element from the animals collection and adds it to the call to pluralise, along with non-plural-words</p> <pre><code>(map (partial pluralise non-plural-words) animals)\n</code></pre> <p>Using partial here is like calling <code>(pluralise non-plural-words ,,,)</code> but each time including an element from animals where the <code>,,,</code> is.</p>"},{"location":"thinking-functionally/map-with-partial/#learning-at-the-repl","title":"Learning at the REPL","text":"<p>At first I was getting incorrect output, <code>[\"deer\" \"sheep\" \"shrimp\"]</code>, then I realised that it was returning the non-plural-words instead of pluralised animals.  The arguments from the partial function were being sent in the wrong order.  So I simply changed the order in the pluralise function and it worked.</p> <p>I checked this by adding some old-fashioned print statement.</p> <pre><code>(defn pluralise-wrong-argument-order\n  \"Pluralise a given string value\"\n  [animal non-plural-words ]\n  (if (some #{animal} non-plural-words)\n    (do\n      (println (str animal \" its true\"))\n      animal)\n    (do\n      (println (str animal \" its false\"))\n      (str animal \"s\"))))\n</code></pre>"},{"location":"thinking-functionally/partial-functions/","title":"Currying &amp; Partial Functions","text":"<p>Clojure does not support automatic currying, (+3) would result in applying + to 3, resulting with number 3 instead of a function that adds 3 as in Haskell. Therefore, in Clojure we use partial that enables the equivalent behavior.</p> <pre><code>(defn sum\n  \"Sum two numbers together\"\n  [number1 number2]\n  (+ number1 number2))\n\n(sum 1 2)\n;; =&gt; 3\n</code></pre> <p>If you try and evaluate <code>sum</code> with a single value then you get an arity exception</p> <pre><code>(sum 1)\n;; =&gt; clojure.lang.ArityException\n;; =&gt; Wrong number of args (1) passed to: functional-concepts/sum\n</code></pre> <p>If we did need to call sum with fewer than the required arguments, for example if we are mapping sum over a vector, then we can use partial to help us call the sum function with the right number of arguments.</p> <p>Lets add the value 2 to each element in our collection</p> <pre><code>(map (partial sum 2) [1 3 5 7 9])\n</code></pre>"},{"location":"thinking-functionally/partial-functions/#using-functions-on-more-arguments-than-they-can-normally-take","title":"Using functions on more arguments than they can normally take","text":"<p>The <code>reduce</code> function can only work on a single collection as an argument (or a value and a collection), so an error occurs if you wish to reduce over multiple collections.</p> <pre><code>(reduce + [1 2 3 4])\n;; =&gt; 10\n\n(reduce + [1 2 3 4] [5 6 7 8])\n;; returns an error due to invalid arguments\n</code></pre> <p>However, by using partial we can take one collection at once and return the result of reduce on each of those collections.</p> <pre><code>(map (partial reduce +) [[1 2 3 4] [5 6 7 8]])\n</code></pre> <p>In the above example we map the partial reduce function over each element of the vector, each element being a collection.</p>"},{"location":"thinking-functionally/partial-functions/#using-partial-to-set-a-default-value","title":"Using partial to set a default value","text":"<p>We can use the partial function to create a default message that can be just given just the custom part.  For example, if we want to have a default welcome message but include a custom part to the message at the end.</p> <p>First we would define a function that combines parts of the message together.</p> <pre><code>(defn join-strings\n  \"join one or more strings\"\n  [&amp; args]\n  (apply str args))\n</code></pre> <p>The [&amp; args] argument string says take all the arguments passed and refer to them by the name args.  Its the &amp; character that has the semantic meaning, so any name after the &amp; can be used, although args is common if there is no domain specific context involved.</p> <p>We can simply call this function with all the words of the message.</p> <pre><code>(join-strings \"Hello\" \" \" \"Clojure\" \" \" \"world\")\n;; \u21d2 \"Hello Clojure world\"\n</code></pre> <p>Now we define a name called <code>wrap-message</code> that can be used to wrap the start of our message.  This name binds to a partial function call to <code>join-strings</code> which send that function the default message and any custom message you add when evaluate <code>wrap-message</code></p> <pre><code>(def wrap-message (partial join-strings \"Hello Clojurians in \"))\n\n(wrap-message)\n;; \u21d2 \"Hello Clojurians in \"\n\n(wrap-message \"London\")\n ;; =&gt; \"Hello Clojurians in London\"\n</code></pre>"},{"location":"thinking-functionally/partial-functions/#currying-in-clojure","title":"Currying in clojure","text":"<p>Currying is the process of taking some function that accepts multiple arguments, and turning it into a sequence of functions, each accepting a single argument.  Or put another way, to transform a function with multiple arguments into a chain of single-argument functions.</p> <p>Currying relies on having fixed argument sizes, whereas Clojure gets a lot of flexibility from variable argument lengths (variable arity).</p> <p>Clojure therefore has the partial function gives results similar to currying, however the <code>partial</code> function also works with variable functions.</p> <p><code>partial</code> refers to supplying some number of arguments to a function, and getting back a new function that takes the rest of the arguments and returns the final result</p> <p>One advantage of <code>partial</code> is to avoid having to write your own anonymous functions</p>"},{"location":"thinking-functionally/partial-functions/#useful-references","title":"Useful references","text":"<ul> <li>Partial function applications for humans</li> </ul>"},{"location":"thinking-functionally/pattern-matching/","title":"Pattern matching","text":"<p>Fixme work in progress</p>"},{"location":"thinking-functionally/pattern-matching/#regular-expression","title":"Regular Expression","text":""},{"location":"thinking-functionally/pattern-matching/#destructuring","title":"Destructuring","text":""},{"location":"thinking-functionally/persistent-data-structures/","title":"Persistent data structures","text":""},{"location":"thinking-functionally/polymorphism/","title":"Polymorphic function definitions","text":"<p>Polymorphic means many forms.</p> <p>The simplest example of polymorphism in Clojure is a function definition that acts differently based on the number of arguments passed.</p> <p>Usually you define a function with one set of arguments, either none <code>[]</code>, one <code>[one]</code> or many <code>[any number of args]</code>, using the basic syntax</p> <pre><code>(defn name\n\"I am the doc string to describe the function\"\n  [args]\n  (str \"define your behaviour here\"))\n</code></pre> <p>Instead of writing multiple functions with the same name that each take different numbers of arguments, you can use the following polymorphic syntax in Clojure</p> <pre><code>(defn name\n  \"I am the doc string to describe the function\"\n  ([]\n    (str \"behaviour with no args\"))\n  ([one]\n    (str \"behaviour with one arg\"))\n  ([one two &amp; args]\n    (str \"behaviour with multiple args\")))\n</code></pre> <p>Note Write a simple function called <code>i-am-polly</code> that returns a default message when given no arguments and a custom message when given a custom string as an argument</p> <pre><code>(defn i-am-polly\n  ([] (i-am-polly \"My name is polly\"))\n  ([message] (str message)))\n\n(i-am-polly)\n(i-am-polly \"I call different behaviour depending on arguments sent\")\n</code></pre>"},{"location":"thinking-functionally/pure-functions/","title":"Pure functions","text":"<p>A function is considered pure if does not side effects or is affected by side causes.  A pure function does not change any other part of the system and is not affected by any other part of the system.</p> <p>When you pass arguments to a function and that function returns a value without interacting with any other part of the system, then that function is considered pure.</p> <p>Should something from outside a function be allowed to affect the result of evaluating a function, or if that function be allowed to affect the outside world, then its an impure function.</p> <p></p> <p>So lets look at a simple code example</p> <pre><code>(defn add-numbers [number1 number2]\n  (+ number1 number2))\n\n(add-numbers 1 2)\n</code></pre> <p>Lets look at each line of this suggested answer</p> <pre><code>;; function takes 2 arguments\n;; function uses both arguments for result\n(defn add-numbers [number1 number2]\n  (+ number1 number2))\n\n;; specific values are passed as arguments\n(add-numbers 1 2)\n</code></pre>"},{"location":"thinking-functionally/pure-functions/#notewrite-a-pure-function-that-adds-two-numbers-together","title":"Note::Write a pure function that adds two numbers together ?","text":""},{"location":"thinking-functionally/pure-functions/#an-example-with-map","title":"An example with map","text":"<p>Note Define a collection called numbers and write a named function that increments each number of the numbers collection. Is your function pure or impure ?</p> <pre><code>(def numbers '(5 4 3 2 1))\n\n(defn increment-numbers []\n  (map inc numbers))\n\n(increment-numbers)\n</code></pre> <p>The function takes no arguments and is pulling in a value from outside the function.  This is a trivial example, but if all your code is like this it would be more complex.  If the value pointed to by <code>numbers</code> is mutable and changes before the <code>increment-numbers</code> function is called then you will get different results.</p> <p>Here is a Pure function example</p> <pre><code>(def numbers '(5 4 3 2 1))\n\n(defn increment-numbers [number-collection]\n  (map inc number-collection))\n\n(increment-numbers numbers)\n</code></pre> <p>In this example we are explicitly passing the <code>numbers</code> collection to the function.  The function works on passed value and returns a predictable result.</p>"},{"location":"thinking-functionally/recursion-polymorphism/","title":"Recursion &amp; Polymorphism","text":"<p>Fixme work in progress</p> <p>The following <code>sum</code> function will calculate the value of adding all the elements in a collection.  You can alter the results by adding a starting value to the calculation as a second argument when calling <code>sum</code></p> <pre><code>(defn sum\n  ([vals] (sum vals 0))\n  ([vals accumulating-total]\n    (if (empty? vals)\n      accumulating-total\n      (sum (rest vals) (+ (first vals) accumulating-total)))))\n\n(sum [2 7 9 11 13])\n(sum [1])\n(sum [2 7 9 11 13] 9)\n</code></pre> <p>Rather than duplicate the calculation, the behaviour of calling <code>sum</code> with just a collection simply calls <code>sum</code> again, this time passing a starting value of zero.</p>"},{"location":"thinking-functionally/recursion/","title":"Recursion","text":"<p>Fixme work in progress</p> <p>Recursion is used greatly in Clojure to iterate through data and as anything can be treated as data in Clojure you can understand why.</p> <p>The constructs available in Clojure for recursion include</p> <ul> <li><code>loop</code> and <code>recur</code></li> <li>Named function that calls itself</li> <li><code>map</code>, <code>reduce</code>, <code>filter</code>, <code>remove</code>, etc.</li> <li><code>for</code></li> </ul>"},{"location":"thinking-functionally/recursion/#recursively-calling-the-same-function","title":"Recursively calling the same function","text":"<p>Lets iterate though a collection using recursion by writing a function that calls itself</p> <pre><code>(defn recursively-use-a-collection [collection]\n  (println (first collection))\n  (if (empty? collection)\n    (print-str \"no more values to process\")\n    (recursively-use-a-collection  (rest collection))))\n\n(recursively-use-a-collection [1 2 3])\n</code></pre> <p>Lets take this recursive approach to create a function that can tell us the length of a collection (list or vector)</p> <p>We define a function that takes a collection of an argument.  The collection is tested to see if it is empty and if so a zero value is returned.  If the collection is not empty, then we</p> <pre><code>(defn length [collection]\n  (if (empty? collection)\n    0\n    (+ 1 (length (rest collection)))))\n;; =&gt; #'clojure-through-code.01-basics/length\n</code></pre> <p>If we call the <code>length</code> function with an empty collection, then the <code>empty?</code> condition will return true and the <code>if</code> expression will evaluate the first expression, 0, returning 0.</p> <pre><code>(length [])\n;; =&gt; 0\n</code></pre> <p>If we call the <code>length</code> function with a collection containing 3 values, then the <code>empty?</code> function will return <code>false</code> and the <code>if</code> function will evaluate the second expression.</p> <p>The second expression starts with a simple counter, using the <code>+</code> function and the value one</p> <pre><code>(length [0 1 2])\n;; =&gt; 3\n</code></pre> <pre><code>(+ 1 (length [1 2]))\n(+ 1 (+ 1 (length [2])))\n(+ 1 (+ 1 (+ 1 (length []))))\n(+ 1 (+ 1 (+ 1 0)))\n\n(length (range 24))\n;; =&gt; 24\n</code></pre> <p>(defn length [collection]   (kk))</p>"},{"location":"thinking-functionally/recursion/#further-recursion-examples","title":"Further recursion examples","text":"<p>Other functions to consider</p> <ul> <li>every</li> <li>accumulating / accumulative</li> <li>keep</li> </ul>"},{"location":"thinking-functionally/sequence-abstractions/","title":"Sequence abstraction","text":"<p>Fixme work in progress</p> <pre><code>(first '(1 2 3 4 5))\n(rest '(1 2 3 4 5))\n(last '(1 2 3 4 5))\n</code></pre> <pre><code>(defn nth [items n]\n (if (= n 0)\n   (first items)\n   (recur (rest items) (- n 1))))\n\n(define squares '(0 1 4 9 16 25))\n\n(nth squares 3)\n</code></pre>"},{"location":"thinking-functionally/sequences/","title":"Sequences","text":"<p>Fixme work in progress</p> <p>Data structures can be built by combining functions</p> <pre><code>(cons 1 (cons 2  (cons 3  (cons 4  nil))))\n</code></pre> <pre><code>(-&gt;&gt;\n nil\n (cons 4)\n (cons 3)\n (cons 2)\n (cons 1))\n</code></pre>"},{"location":"thinking-functionally/side-effects/","title":"Side effects","text":"<p>A side effect is something that creates a change outside of the current code scope, or something external that affects the behaviour or result of executing the code in the current scope.</p>"},{"location":"thinking-functionally/side-effects/#nondeterministic-the-complexity-iceberg","title":"Nondeterministic - the complexity iceberg","text":"<p>When you have side effects, you cannot reason accurately about a piece of the code.</p> <p>In order to understand a piece of code you must look at all possible side effects created in all lines of code to ensure you fully understand the result of executing your code.</p> <p>With side effects in your system, complexity is hidden, causing a far greater risk of a dangerous situation.</p>"},{"location":"thinking-functionally/side-effects/#side-causes-side-effects","title":"Side causes - side effects","text":"<p>You can think about these effects is in two specific areas, Side Causes and Side Effects</p> <ul> <li> <p>Side Causes - are where other pieces of code (function) or state change affects the behaviour of a function.</p> </li> <li> <p>Side Effects - are where the current code (function) affects the rest of the system</p> </li> </ul> <p></p>"},{"location":"thinking-functionally/side-effects/#hintside-causes-term","title":"Hint::Side Causes term","text":"<p>The term of side causes was coined by Kris Jenkins in the superb article What is Functional Programming?</p>"},{"location":"thinking-functionally/tail-recursion/","title":"Tail recursion","text":"<p>Fixme work in progress</p> <p>If we generate a very large collection we run the risk of blowing our heap space.  For example we could use range to generate a very large collection, say a vector containing 10 billion values</p> <p>Don't try this example below</p> <pre><code>(vec (range 0 9999999999))\n;; this will crash after a short while as it will use up all your heap space\n</code></pre> <p>Using tail call optimisation (tail recursion) allows us to reuse a memory location when we call a function recursively.  This tail recursion is not part of the underlying Java Virtual Machine (JVM), so instead Clojure has a specific function called <code>recur</code></p> <p>The <code>recur</code> function allows the processing of a very large data set without blowing the heap space because the memory space will be reused.</p> <p>The <code>recur</code> function must be the last expression in order to work.</p> <pre><code>(defn sum\n  ([vals] (sum vals 0))\n  ([vals accumulating-total]\n   (if (empty? vals)\n     accumulating-total\n     (recur (rest vals) (+ (first vals) accumulating-total)))))\n\n(sum (vec (range 0 9999999)))\n</code></pre>"},{"location":"thinking-functionally/threading-macros/","title":"Threading macros","text":"<p>The thread-first <code>-&gt;</code> and thread-last <code>-&gt;&gt;</code> macros allow Clojure code to be written in a more sequential style and with a more terse syntax.  This can sometimes make code easier to understand by humans.</p> <p>Using the thread-first macro, <code>-&gt;</code>, the result of the first evaluation is passed as the first argument to the next function and so on.</p> <p>```clojure (-&gt;  (clojure.string/lower-case \"HELLO\")  (str \", Clojure world\")) <pre><code>The value hello is converted to lower case and that result is passed as the first argument to the next function.  The string function is then evaluated with this new argument and the final \"hello, Clojure world\" string is returned as the result.\n\n  The thread-last macro `-&gt;&gt;` passes the result of the first evaluation as the **last argument** to the next expression.\n\n```clojure\n(-&gt;&gt;  \" this\"\n (str \" is\")\n (str \" backwards\"))\n</code></pre></p>"},{"location":"thinking-functionally/threading-macros/#hintparens-optional","title":"Hint::Parens optional","text":"<p>function calls that only take one argument, the one passed by earlier expressions, can be included in the threading macro code without the surrounding <code>()</code> parens.</p>"},{"location":"thinking-functionally/threading-macros/#reading-clojure-code","title":"Reading Clojure code","text":"<p>To read Clojure it is common to start from the inside out, as this is how the Clojure reader also works.  This style is inherited from Lisp of which Clojure is an implementation.</p> <p>The following code is written in classic Lisp style.</p> <pre><code>(reverse\n  (sort-by val (frequencies\n                 (remove common-english-words\n                   (map #(clojure.string/lower-case %)\n                        (re-seq #\"[a-zA-Z0-9|']+\"\n                                (slurp book.txt)))))))\n</code></pre> <p>Reading inside out:</p> <ol> <li>slurp in the contents of the book.txt file, converting it to a string.</li> <li>use a regular expression to create a new sequence where the book is a sequence of individual strings for each word.</li> <li>convert each string in the sequence by mapping the lower-case function over each element of the sequence.</li> <li>remove common english words such as the and and from the sequence.</li> <li>count how many times each word occurs and pair the string with its frequency in the book.</li> <li>reverse the order of the sequence by the value of frequency, so the most used word is at the start of the sequence.</li> </ol> <p>This function uses the var <code>common-english-words</code> which is defined as:</p> <pre><code>(def (set\n       (clojure.string/split (slurp \"common-english-words.txt\") #\",\" )))\n</code></pre> <p>This takes a comma separated file of words and splits them.  The words are put into a set so only one instance of each word is included.</p>"},{"location":"thinking-functionally/threading-macros/#rewriting-the-code-with-threading-macros","title":"Rewriting the code with threading macros","text":"<pre><code>(-&gt;&gt; (slurp book.txt)\n     (re-seq #\"[a-zA-Z0-9|']+\" ,,,)\n     (map #(clojure.string/lower-case %))\n     (remove common-english-words)\n     frequencies\n     (sort-by val)\n     reverse)\n</code></pre> <p><code>frequencies</code> and <code>reverse</code> only take one argument, so they do not require surrounding <code>()</code> inside the threading macro.</p> <p>The common-english-words var is fairly easy to read, so probably doesn't need to be written using a threading macro, however, for completeness here is a thread-first example.</p> <pre><code>(def common-english-words\n  (-&gt; (slurp \"common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre>"},{"location":"thinking-functionally/threading-macros/#hintmacroexpand","title":"Hint::Macroexpand","text":"<p>use <code>macroexpand-1</code> around the threading macro code to show resulting lisp style Clojure code.  Clojure editors also provide evaluation functions that will macroexpand.</p>"},{"location":"thinking-functionally/transducers/","title":"Transducers","text":"<p>Transducers provide an efficient way to transform values from a collection or stream of data, eg. core.async channel, java.jdbc database query (0.7.0 upward) or a network stream etc.</p> <p>Transformations are applied directly to a stream of data without first creating a collection.</p> <p>Multiple transducers are composed into a single transforming function, walking the data elements only once and without the need for intermediate collections.  </p> <p>One Transducer benefit is to allow the design to switch from a seq-based implementation to a core.async implementation using channels</p> <p>Transducers: Clojure.org Transducer use cases </p> <p>Basics Transducer walkthrough</p> <p>Simple examples of Clojure Transducers</p> <p> </p> <p> </p>"},{"location":"thinking-functionally/transducers/#evolving-design","title":"Evolving design","text":"<p>Each element of the data collection is acted upon by a composition of each transducer in an expression, making them more efficient than a applying one expression after another (e.g. as with a thread macro or composed list expressions). </p> <p>Transducers provide benefits like lazy evaluation and alternative performance trade-offs.</p> <p>Nested calls</p> <pre><code>(reduce + (filter odd? (map #(+ 2 %) (range 0 10))))\n</code></pre> <p>Functional composition</p> <pre><code>(def xform\n  (comp\n    (partial filter odd?)\n    (partial map #(+ 2 %))))\n  (reduce + (xform (range 0 10)))\n</code></pre> <p>Thread macro</p> <pre><code>    (defn xform [xs]\n      (-&gt;&gt; xs\n           (map #(+ 2 %))\n           (filter odd?)))\n    (reduce + (xform (range 0 10)))\n</code></pre> <p>Transducer</p> <pre><code>(def xform\n  (comp\n    (map #(+ 2 %))\n    (filter odd?)))\n(transduce xform + (range 0 10))\n</code></pre> <p>The order of combinators in a transducer is the same as a thread macro (natural order). </p>"},{"location":"thinking-functionally/transducers/#coreasync","title":"core.async","text":"<p>Transducers were introduced into the Clojure language to provide a common abstraction to avoid re-implmentation of clojure.core transformation functions specific to core.async.</p> <p>in a large part to support processing data to and from a core.async channel.</p> <p>The Clojure maintainers discovered they were re-implementing filter, map, partition, etc. on core.async and realized it would be better to have an abstraction for the transforms independent of the source and destination of data.</p> <p>The xform can be used with an core.async channel</p> <p>Transducer with core.async</p> <pre><code>(chan 1 xform)\n</code></pre> <p>an optional arg when creating a channel, causing a transform to be applied to all data that goes through the channel</p>"},{"location":"thinking-functionally/transducers/#database-queries","title":"Database queries","text":"<p>Typical database access involves passing in functions to transform rows and process the transformed result set</p> <p><code>java.jdbc</code> 0.7.0-beta1 onwards can also apply transducers to \u201creducible queries\u201d (and reducible result sets).</p> <p>Create a reducible query which is passed to transforming function, e.g. reducers, transducers, plain ol\u2019 <code>reduce</code> and <code>into</code> etc </p>"},{"location":"thinking-functionally/transducers/#simplified-description","title":"Simplified description","text":"<p>Transducers are recipes what to do with a sequence of data without knowledge what the underlying sequence is (how to do it). It can be any seq, async channel or maybe observable.</p> <p>They are composable and polymorphic.</p> <p>The benefit is, you don't have to implement all standard combinators every time new data source is added. Again and again. As resulting effect you as user are able to reuse those recipes on different data sources.</p> <p>https://stackoverflow.com/questions/26317325/can-someone-explain-clojure-transducers-to-me-in-simple-terms</p> Work In Progress, sorry <p>A very messy brain dump of ideas to tidy up. Pull requests are welcome</p> <p>Clojure.core functions such as map and filter are lazy, however they also generate containers for lazy values when chained together. </p> <p>Without holding onto the head of the collection, large lazy sequences aren't created but intermediate abstractions are still created for each lazy element.</p>"},{"location":"thinking-functionally/transducers/#reducing-functions","title":"Reducing functions","text":"<p>Reducing functions are those that take two arguments: </p> <ul> <li>a result so far </li> <li>an input. </li> </ul> <p>The reducing function returns a new result (so far). </p> <p>For example +: With two arguments, you can think of the first as the result so far and the second as the input.</p> <p>A transducer could now take the + function and make it a twice-plus function (doubles every input before adding it). This is how that transducer would look like (in most basic terms):</p> <p>Reducing function</p> <pre><code>(defn double\n  [rfn]\n  (fn [r i]\n    (rfn r (* 2 i))))\n</code></pre> <p>For illustration substitute rfn with + to see how + is transformed into twice-plus:</p> <p>Reducing function - twice plus</p> <pre><code>(def twice-plus ;; result of (double +)\n  (fn [r i]\n    (+ r (* 2 i))))\n\n(twice-plus 1 2)  ;-&gt; 5\n(= (twice-plus 1 2) ((double +) 1 2)) ;-&gt; true\n</code></pre> <p>Calling the reducing function</p> <pre><code>(reduce (double +) 0 [1 2 3])\n\n;; =&gt; 12\n</code></pre> <p>Reducing functions returned by transducers are independent of how the result is accumulated because they accumulate with the reducing function passed to them. </p> <p><code>conj</code> takes a collection and a value and returns a new collection with that value appended.</p> <pre><code>(reduce (double conj) [] [1 2 3])\n;; =&gt; [2 4 6]\n</code></pre> <p>Transducers are independent of the kind of data is passed.</p> <p>optimisation goes beyond eliminating intermediate streams; it is possible to perform operations in parallel.</p>"},{"location":"thinking-functionally/transducers/#pmap","title":"pmap","text":"<p>Use <code>pmap</code> when mapping an expensive function over a sequence, making the operation parallel.  No other changes to the code are required. </p> <p>Transducers will still be faster if the pmap function creates intermedicate data structures.</p> <p>A transducer clear definition is here:</p> <p>Transducers are a powerful and composable way to build algorithmic transformations that you can reuse in many contexts.</p>"},{"location":"thinking-functionally/transducers/#reducing-functions_1","title":"Reducing functions","text":"<p>Population a local Village</p> <p>The  <pre><code>(def village\n  [{:home :north :family \"smith\" :name \"sue\" :age 37 :sex :f :role :parent}\n   {:home :north :family \"smith\" :name \"stan\" :age 35 :sex :m :role :parent}\n   {:home :north :family \"smith\" :name \"simon\" :age 7 :sex :m :role :child}\n   {:home :north :family \"smith\" :name \"sadie\" :age 5 :sex :f :role :child}\n\n   {:home :south :family \"jones\" :name \"jill\" :age 45 :sex :f :role :parent}\n   {:home :south :family \"jones\" :name \"jeff\" :age 45 :sex :m :role :parent}\n   {:home :south :family \"jones\" :name \"jackie\" :age 19 :sex :f :role :child}\n   {:home :south :family \"jones\" :name \"jason\" :age 16 :sex :f :role :child}\n   {:home :south :family \"jones\" :name \"june\" :age 14 :sex :f :role :child}\n\n   {:home :west :family \"brown\" :name \"billie\" :age 55 :sex :f :role :parent}\n   {:home :west :family \"brown\" :name \"brian\" :age 23 :sex :m :role :child}\n   {:home :west :family \"brown\" :name \"bettie\" :age 29 :sex :f :role :child}\n\n   {:home :east :family \"williams\" :name \"walter\" :age 23 :sex :m :role :parent}\n   {:home :east :family \"williams\" :name \"wanda\" :age 3 :sex :f :role :child}])\n</code></pre></p> <p>Define a reducing expression to return the number of children in the village.</p> <pre><code>(def children \n  (r/map #(if (= :child (:role %)) 1 0)))\n</code></pre> <p>Call the expression <pre><code>(r/reduce + 0 (children village))\n;;=&gt; 8\n</code></pre></p> <p>Using a transducer to add up all the mapped values</p> <p>create the transducers using the new arity for map that takes the function, no collection</p> <pre><code>(def child-numbers (map #(if (= :child (:role %)) 1 0)))\n</code></pre> <p>Use transduce (c.f r/reduce) with the transducer to get the answer <pre><code>(transduce child-numbers + 0 village)\n;;=&gt; 8\n</code></pre></p> <p>It is really powerful when taking subgroups in account, e.g to know how many children in the Brown Family</p> <p>Reducer to count children in Brown family</p> <p>Create the reducer to select members of the Brown family</p> <pre><code>(def brown-family-children\n  (r/filter #(= \"brown\" (string/lower-case (:family %)))))\n</code></pre> <p>compose a composite function to select the Brown family and map children to 1</p> <pre><code>(def count-brown-family-children \n  (comp ex1a-map-children-to-value-1 brown-family-children))\n</code></pre> <p>reduce to add up all the Brown children <pre><code>(r/reduce + 0 (ex2a-count-brown-family-children village))\n;;=&gt; 2\n</code></pre></p>"},{"location":"thinking-functionally/transducers/#references","title":"References","text":"<p>Transducers - Clojure next big idea</p>"},{"location":"using-data-structures/","title":"Using data structures","text":"<p>Data structures in Clojure are used to model information and data, within a particular namespace.  Functions are used to run behaviour over the data structures.</p> <p>Lets look at some of the common functions that are used in Clojure with data structures</p> <p>fixme the below content is work in progress, sorry.</p>"},{"location":"using-data-structures/#managing-return-values","title":"Managing Return values","text":"<p>If you run a function over a data structure, you may not always get back the type of value you want.  It easy to wrap a function around to give you the desired value type.</p> <p>Note Use the <code>str</code> function to get a string from person, rather than a set of characters</p> <pre><code>(first person)\n(rest person)\n\n(str (first person))\n\n;; How do we return the rest of the string as a string ?\n(str (rest person))\n(map str (rest person))\n(str (map str (rest person)))\n(apply str (rest person))\n</code></pre> <p>You can get the value of this map</p> <pre><code>(def luke {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"})\n(def darth {:name \"Darth Vader\"    :skill \"Crank phone calls\"})\n(def jarjar {:name \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"})\n\n(get luke :skill)\n</code></pre>"},{"location":"using-data-structures/#immutability","title":"Immutability","text":"<p>When you use functions on data structures, although they can return a new value they do not change the original data structure.</p> <p>Lets define a name for a data structure</p> <pre><code>(def name1 [1 2 3 4])\n</code></pre> <p>when we evaluate that name we get the original data we set</p> <pre><code>name1\n</code></pre> <p>Now we use a function called conj to adds (conjoin) another number to our data structure</p> <pre><code>(conj name1 5)\n</code></pre> <p>This returns a new value without changing the original data structure</p> <pre><code>name1\n</code></pre> <p>We cant change the original data structure, it is immutable.  Once it is set it cant be changed. However, if we give a name to the result of changing the original data structure, we can refer to that new data structure</p> <pre><code>(def name2(conj name1 5))\n</code></pre> <p>Now name2 is the new data structure, but name1 remains unchanged</p> <pre><code>name2\nname1\n</code></pre> <p>So we cannot change the data structure, however we can achieve something that looks like we have changed it.  We can re-assign the original name to the result of changing the original data structure</p> <pre><code>(def name2(conj name1 5))\n</code></pre> <p>Now name1 and name2 are the same result</p> <pre><code>name2\nname1\n</code></pre> <p>An analogy</p> <p>You have the number 2.  If you add 1 to 2, what value is the number 2?</p> <p>The number 2 is still 2 no mater that you add 1 to it, however, you get the value 3 in return</p>"},{"location":"using-data-structures/#creating-new-data-structures","title":"Creating new data structures","text":"<p>Use concat to add lists or vectors together</p> <pre><code>(concat [1 2] '(3 4)) ; =&gt; (1 2 3 4)\n</code></pre> <p>Use filter, map to interact with collections</p> <pre><code>(map inc [1 2 3]) ; =&gt; (2 3 4)\n(filter even? [1 2 3]) ; =&gt; (2)\n</code></pre> <p>Use reduce to reduce them</p> <pre><code>(reduce + [1 2 3 4])\n; = (+ (+ (+ 1 2) 3) 4)\n; =&gt; 10\n</code></pre> <p>Reduce can take an initial-value argument too</p> <pre><code>(reduce conj [] '(3 2 1))\n; = (conj (conj (conj [] 3) 2) 1)\n; =&gt; [3 2 1]\n</code></pre> <p>Use cons to add an item to the beginning of a list or vector</p> <pre><code>(cons 4 [1 2 3]) ; =&gt; (4 1 2 3)\n(cons 4 '(1 2 3)) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use conj to add an item to the beginning of a list, or the end of a vector</p> <pre><code>(conj [1 2 3] 4) ; =&gt; [1 2 3 4]\n(conj '(1 2 3) 4) ; =&gt; (4 1 2 3)\n</code></pre>"},{"location":"using-data-structures/applying-functions/","title":"Applying functions to data structures","text":"<p>Applying a functions behaviour to the elements of a data structure</p>"},{"location":"using-data-structures/destructuring/","title":"Destructuring","text":"<p>Destructuring is a form of pattern matching that is common in Clojure.  Destructuring allow you to pull out the specific elements from a collection.</p> <p>Destructuring is commonly used with the <code>let</code> method for creating local bindings (locally scoped names).</p> <pre><code>(let [[a b c &amp; d :as e] [1 2 3 4 5 6 7]]\n  [a b c d e])\n\n(let [[[x1 y1][x2 y2]] [[1 2] [3 4]]]\n  [x1 y1 x2 y2])\n\n;; with strings\n(let [[a b &amp; c :as str] \"asdjhhfdas\"]\n  [a b c str])\n\n;; with maps\n(let [{a :a, b :b, c :c, :as m :or {a 2 b 3}}  {:a 5 :c 6}]\n  [a b c m])\n</code></pre> <p>It is often the case that you will want to bind same-named symbols to the map keys. The :keys directive allows you to avoid the redundancy:</p> <pre><code>(let [{fred :fred ethel :ethel lucy :lucy} m] )\n</code></pre> <p>This can be written in a shorter form as follows:</p> <pre><code>(let [{:keys [fred ethel lucy]} m] )\n</code></pre> <p>As of Clojure 1.6, you can also use prefixed map keys in the map destructuring form:</p> <pre><code>(let [m {:x/a 1, :y/b 2}\n      {:keys [x/a y/b]} m]\n  (+ a b))\n</code></pre> <p>As shown above, in the case of using prefixed keys, the bound symbol name will be the same as the right-hand side of the prefixed key. You can also use auto-resolved keyword forms in the :keys directive:</p> <pre><code>(let [m {::x 42}\n      {:keys [::x]} m]\n  x)\n</code></pre>"},{"location":"using-data-structures/lazy-sequences/","title":"Lazy Sequences","text":"<p>Sequences are an interface for logical lists, which can be lazy.  \"Lazy\" means that a sequence can define an infinite series, like so:</p> <pre><code>(range 4)\n</code></pre> <p>If you evaluate <code>(range)</code> just by itself it will return an infinite number of integers, well at least until your computers memory space fills up.</p> <p>So we dont blow up our memory and just get the values we want we can use <code>range</code> in conjunction with other functions that define how many numbers we actually want.</p> <p>For example, if we just wanted the first four numbers from the infinite sequence of <code>range</code> we could specify that with the <code>take</code> function</p> <pre><code>(take 4 (range)) ;  (0 1 2 3)\n</code></pre> <p>Here the range function is being lazy, because it will only generate the first 4 numbers in its sequence.</p> <p>Clojure (and Lisps in general) often evaluate at the last possible moment, usually when they have been given more specific content.</p>"},{"location":"using-data-structures/mapping-data-structures/","title":"Mapping functions over data structures","text":"<p>Map allows you to work over one or more data sets, applying the function to each element of each of the data structures.</p> <p>When the data structures are of equal size, then the same sized data structure is returned.</p> <pre><code>(map + [1 2 3] [1 2 3])\n;; =&gt; (2 4 6)\n</code></pre> <p>If one data structure is smaller, then the function is only applied up to the last element of the smallest data structure.</p> <pre><code>(map + [1 2 3] [1 2])\n;; =&gt; (2 4)\n\n(map + [1 2 3] [1])\n;; =&gt; (2)\n\n(map + [1 2 3] [])\n;; =&gt; ()\n\n(map + [1 2 3])\n;; =&gt; (1 2 3)\n</code></pre> <p>Lets look at another example.  Here we have a pre-defined Fibonacci sequence up to the first 12 values.</p> <pre><code>(def fibonacci-sequence [1 2 3 5 8 13 21 34 55 89 144 278])\n</code></pre> <p>If we just want the first 10 values of the sequence, we can use the <code>take</code> function.</p> <pre><code>(take 10 fibonacci-sequence)\n;; =&gt; (1 2 3 5 8 13 21 34 55 89)\n</code></pre> <p>If we want a calculation using the values of the fibonacci-sequence then we can use <code>map</code> with a function.  In this case we are going to generate a range of Integer numbers from 0-9 using the function <code>range</code>.  That range of numbers is then multiplied element by element with the corresponding element in the fibonacci-sequence.</p> <pre><code>(map * (range 10) fibonacci-sequence)\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>So,</p> <ul> <li>0 times 1 is 0,</li> <li>1, times 2 is 2,</li> <li>2 times 3 is 6, etc.</li> </ul> <p>If we evaluate the previous expression part by part, its easier to see what is going on.  First lets evaluate the <code>fibonacci-sequence</code></p> <pre><code>(map * (range 10) [1 2 3 5 8 13 21 34 55 89 144 278])\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>Now lets evaluate the <code>(range 10)</code> function call</p> <pre><code>(map * (0 1 2 3 4 5 6 7 8 9) [1 2 3 5 8 13 21 34 55 89 144 278])\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>We can see the answer is the same, however by evaluating each part of the expression we get an exact view of what is going to happen with the <code>map</code> function.</p>"},{"location":"using-data-structures/sequences/","title":"Sequence abstractions","text":"<p>There are functions that work on all the built in data-structures in Clojure.</p> <p><code>first</code> <code>second</code> <code>rest</code> <code>cons</code></p>"},{"location":"using-data-structures/sequences/#practising-with-lists","title":"Practising with lists","text":"<p>Create a simple collection of developer events.  First use a list of strings, then try a map with keywords.  For each data structure, pull out some of the event details</p> <pre><code>(def developer-events-strings '(\"Devoxx UK\" \"Devoxx France\" \"Devoxx\" \"Hack the Tower\"))\n\n(def developer-events-strings2 (list \"Devoxx UK\" \"Devoxx France\" \"Devoxx\" \"Hack the Tower\"))\n\ndeveloper-events-strings\n\n(first developer-events-strings)\n\n(def developer-events-vector\n  [:devoxxuk :devoxxfr :devoxx :hackthetower] )\n</code></pre> <p>Using a Clojure Vector data structure is a more Clojure approach, especially when the vector contains keywords.  Think of a Vector as an Array, although in Clojure it is again immutable in the same way a list is.</p> <p>Create a slightly more involved data structure, holding more data around each developer events.  Suggest using a map, with each key being the unique name of the developer event.</p> <p>The details of each event (the value to go with the event name key) is itself a map as there are several pieces of data associated with each event name.</p> <pre><code>(def dev-event-details\n  {:devoxxuk     {:URL \"http://jaxlondon.co.uk\"\n                  :event-type \"Conference\"\n                  :number-of-attendees 700\n                  :call-for-papers true}\n   :hackthetower {:URL \"http://hackthetower.co.uk\"\n                  :event-type \"hackday\"\n                  :number-of-attendees 60\n                  :call-for-papers false}})\n</code></pre> <p>Lets call the data structure and see what it evaluates too, it should not be a surprise</p> <pre><code>dev-event-details\n</code></pre> <p>We can ask for the value of a specific key, and just that value is returned</p> <pre><code>(dev-event-details :devoxxuk)\n</code></pre> <p>In our example, the value returned from the :devoxxuk key is also a map, so we can ask for a specific part of that map value by again using its key</p> <pre><code>(:URL (dev-event-details :devoxxuk))\n</code></pre> <p>Define a simple data structure for stocks data using a vector of maps, as there will be one or more company stocks to track.</p> <p>Each map represents the stock information for a company.</p> <p>Get the value of the whole data structure by referring to it by name, ask for a specific element by its position in the array using the <code>nth</code> function.</p> <p>Then try some of the common functions that work on collections.</p> <pre><code>(def portfolio [ { :ticker \"CRM\" :lastTrade 233.12 :open 230.66}\n                 { :ticker \"AAPL\" :lastTrade 203.25 :open 204.50}\n                 { :ticker \"MSFT\" :lastTrade 29.12  :open 29.08 }\n                 { :ticker \"ORCL\" :lastTrade 21.90  :open 21.83 }])\n\nportfolio\n\n(nth portfolio 0)\n\n(nth portfolio 3)\n\n(first portfolio)\n(rest portfolio)\n(last portfolio)\n</code></pre> <p>First and next are termed as sequence functions in Clojure, unlike other lisps, you can use first and next on other data structures too</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Practicalli Clojure","text":"<p>Practicalli Clojure is a hands-on guide to using Clojure throughout all the software development stages.  Live coding videos demonstrate the Clojure REPL workflow in action, showing how to get the most out of the unique approach the language provides.</p> <p>Discover how to make the most of Clojure CLI and community tools, drawing from commercial experiences and community discussions.</p> <p>Practical code examples are supported by discussions of the concepts behind Clojure, including functional programming, \"pure\" functions and a stateless approach with persistent data structures, changing state safely, Java interoperability and tooling around Clojure.</p> <p>John Stevenson, Practical.li</p> <p>Clojure - an elegant language for a more civilised development experience</p>"},{"location":"#clojure-repl-driven-development","title":"Clojure REPL Driven Development","text":"<p>The Clojure REPL is interactive environment used to run Clojure code in both development and production. The REPL workflow provides an instant feedback loop so individual pieces of code (expressions) can be evaluatived, quickly growing confidence with Clojure and rapidly evolving effective designs.</p>"},{"location":"#clojure-language","title":"Clojure Language","text":"<p>Clojure programming language has a strong dynamic type system and a simple syntax that is a joy to work with.  Immutable values and a pragmatic approach to pure functional programming makes it easier to create simple and highly maintainable systems. A specification library ensures values are of the correct shape, especially valuable when receiving data from outside of Clojure.</p> <p>Clojure has an open source license and a large number of open source libraries and tools.  Simple host interoperability allows a even more libraries to be leveraged.</p> <p>Adrian Cockcroft - formally Cloud Architect, Netflix</p> <p>The most productive programmers I know are writing everything in Clojure ... producing ridiculously sophisticated things in a very short time. And that programmer productivity matters.</p> <p>Clojure REPL Workflow overview Clojure REPL</p>"},{"location":"#navigate-the-book","title":"Navigate the book","text":"<p>Use the mouse or built-in key bindings to navigate the pages of the book</p> <ul> <li>P , , : go to previous page</li> <li>N , . : go to next page</li> </ul> <p>Use the search box to quickly find a specific topic</p> <ul> <li>F , S , / : open search dialog</li> <li>Down , Up : select next / previous result</li> <li>Esc , Tab : close search dialog</li> <li>Enter : follow selected result</li> </ul>"},{"location":"#resources","title":"Resources","text":"<p> Practicalli Clojure CLI Config - additional tools via aliases Clojure Aware Editors Practicalli YouTube channel</p>"},{"location":"#sponsor-practicalli","title":"Sponsor Practicalli","text":"<p>All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.</p> <p>Thanks to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support</p>"},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images &amp; stylesheets)."},{"location":"core-async/","title":"Core.async","text":""},{"location":"core-async/#discussion-from-the-clojurians-clojure-uk-slack-channel","title":"Discussion from the clojurians clojure-uk slack channel","text":"<p>recommendation / intro tutorial</p> <p>https://github.com/clojure/core.async/blob/master/examples/walk-through.clj</p> <p>EuroClojure talk about clojure otp library that built on top of core.async because they felt it was too low level</p> <p>At the REPL</p> <ul> <li>if you don\u2019t create channels with non-zero sized buffers, or don\u2019t perform operations in separate threads or go-blocks, then you can end up blocked quite easily</li> </ul> <p>In production be sure to catch exceptions, or at least be logging them. It can be too easy to loose errors (and the processes that threw them)</p> <p>if you make a note of the nrepl port when you start a repl, you can always connect a second repl to the same process to recover from accidental blocking</p>"},{"location":"core-async/#coreasync-and-transducers","title":"core.async and transducers","text":"<p>core.async + transducers</p>"},{"location":"core-async/#manifold-alternative-to-coreasync","title":"Manifold - alternative to core.async","text":"<p>another approach is to use <code>manifold</code></p> <p>it\u2019s use of deferred values makes it harder to block the REPL - but obviously the buffering still has to happen somewhere!</p> <p><code>manifold</code> for general async stuff more than <code>core.async</code></p> <p>use core.async as a way of chaining together bits of data processing. manifold would be good for that too</p> <p>put multiple calls to an external API on a channel and have them \u201cdo their thing\u201d in their own time in the background.  This seems to be a good use for core.async\u2026  Is Manifold is as good / better?</p> <p>If processing streams of data then <code>core.async</code> is fine (as are manifold <code>Stream</code>s) If calls are better suited to promises then consider manifold <code>Deferred</code> If you are wanting streams of promises then manifold is a more complete solution (because the manifold <code>stream</code> and <code>deferred</code> work easily together</p> <p>API calls are generally more promise-like than stream-like (unless your result is an SSE stream or websocket etc)</p> <p>there are <code>promise-chan</code>s in core.async too though</p> <p>Manifold could be used to collect a number of remote resources together in a <code>let</code> which isn't very stream like</p> <p>manifold has two distinct core abstractions - the <code>deferred</code>, which is a promise with callbacks and additional machinery, and the <code>stream</code> which is a umm stream of values, and supports buffering, backpressure etc</p> <p>First call to the API I will get a total back as part of the result and as there is no paging functionality \u201cbuilt in\u201d on the API in question I will need to take the total and figure out how many more calls I need to make to get the \u201crest\u201d of the data.  I was going to do this by throwing the calls onto a channel using core.async\u2026 I am sensing that their promise-y nature would, you feel, be better suited to Manifold Deferred..? a stream or a channel works quite well for that sort of query in my data access lib we actually use a promise of a stream for that sort of access which is an improvement over just a plain stream because it allows easy mixing with other calls which return promises of a value</p> <p>I was intending to stack up API operations in a channel as a queue so that a) I don\u2019t block execution and b) so that I don\u2019t have to use an actual queue (SQS / rabbitMQ etc) I am starting to think I may not have understood the implications of what I want to do\u2026 </p> <p>i'm not sure - are you just trying to get a stream of records from a paginated api ?</p> <p>what are you trying to not block the execution of?</p> <p>The API is not paginated, I need to figure out how many pages there are and stack up the calls.</p> <p>can you pass an offset or something ?</p> <p>What I am looking for is a way to stack work up asynchronously in the background so that my call(s) to the external API don\u2019t lock up the whole app / program for minutes at a time.</p> <p>yes, but there is no \u201cnext\u201d call - the offset and page-size are arbitrary params every call, there is no way to ask for \u201cpage 2 of my last query to the API\u201d</p> <p>a channel of results in core.async is perfectly reasonable, as is a manifold stream of deferred responses</p> <p>so:</p> <ol> <li>Make call for first page</li> <li>Process first page (hopefully async)</li> <li>Use total to work out how many more ops I need to make</li> <li>Fill up channel with calls</li> <li>Consume channel \u201celsewhere\u201d.</li> </ol> <p>is my thesis - does that make sense..?</p> <p>what is the main thread in this context? the app that \u201cruns\u201d which in turn is a hybrid API / webapp</p> <p>core.async itself uses a threadpool, so you might not need to funnel them all down one channel unless you wanted to limit the number of concurrent api calls I would like to do as much concurrently as possible, but it\u2019s not a deal-breaker, serial is fine as long as the work can be \u201ckicked off\u201d and left going. order of results being processed is not important, so concurrency (particularly if it makes the whole thing faster) would be great.</p> <p>I need to make one call to find out how many results match the request, the vendor / curator of the AI in question is not prepared to produce a simplified response to figure out the size of results sets, so I am stuck with that.</p> <p>I am assuming that I need to \u201cdef\u201d the channel(s) and then have a form that is in an evaluated namespace that is \u201cwaiting\u201d for the channel(s) to have something on them..?</p> <p>a common idiom is to return channels/streams/promises as the result of a query fn</p> <p>OK, but how would I consume them without tying up the main thread?</p> <p>many options</p> <ul> <li>put the consuming code inside a core.async <code>go</code> block</li> <li>create a new channel with a transducer and pipe your first channel to that</li> <li>have your api fn take the channel you want responses put on and pass in a channel with a transducer</li> </ul> <p>similarly in manifold,</p> <ul> <li>chain a step onto a deferred https://github.com/ztellman/manifold/blob/master/docs/deferred.md#composing-with-deferreds</li> <li>map a fn over a stream https://github.com/ztellman/manifold/blob/master/docs/stream.md#stream-operators</li> </ul> <p>need some code in an evaluated namespace that was effectively \u201clistening\u201d for there to be \u201cthings\u201d on the channel, just a form at the end of my namespace containing a go block that was consuming a named channel onto which my API function would place \u201cthings\u201d</p> <p>most web or UI frameworks will already have an event loop to do that i\u2019d have expected?</p> <p>order of ops:</p> <ol> <li>Make first query to API</li> <li>Process result, including calculation of how many more ops required</li> <li>Load up a channel with the other calls</li> </ol> <p>It\u2019s an app that will periodically (every hour / day not sure yet) make calls to an API, stash the returned data in a database and an ElasticSearch cluster, and then do it all again the next time.</p> <p>might want to add [4] concatenate results from each of the page queries into a single record stream</p> <p>but what will consume the eventual record stream ?</p> <p>This makes the API into a smaller, custom dataset that can be interrogated via Kibana</p> <p>I am not saying I don\u2019t want to add \u201c[4] concatenate results from each of the page queries into a single record stream\u201d, but I can\u2019t think of why I would do that, and that is probably me being ignorant of the benefits etc.  Please could you explain to me why I would add this step - I really am asking, not being a prick, I promise </p> <p>do you want to expose your downstream consumers to an additional level of structure (pages) which is an implementation feature of the upstream API  ?</p> <p>No</p> <p>I want to take each of the 100 / 1000 / 10000 results and store them as individual documents in ES and as JSONB fields in Postgres</p> <p>The API I am \u201charvesting\u201d has a 90 day sliding window, so over time the queries I make will have different results.  I don\u2019t want to keep track of the last article I harvested, nor do I want to have to \u201cfind\u201d it in the results to then get all the newer ones.  It\u2019s easier to just \u201ceat\u201d the whole response every time and reply on ES refusing to re-import a document with an existing id (into the same index) and on postgres\u2019s ability to enforce a \u201cunique\u201d index on the id field.</p> <p>but I can\u2019t \u201cget\u201d all of the results in one query, the API limits \u201cpages\u201d to 1000 results, so I need to be able to stack up calls and execute them in an async, non-blocking manner.</p> <p>yep, so you can concatenate the pages into a single record-stream, and process each of the records individually</p> <p>OK, I like the sound of this in principle, and I think I am sort of doing that already with the synchronous, manual approach, as I get 100 articles back and then I do a doseq over the vector of maps to do INSERT queries into postgres and PUT calls to ES</p> <p>What do you mean by a \u201crecord-stream\u201d?</p> <p>by \"record stream\" i mean a conceptual sequence of individual records... could be on a core.async <code>chan</code> or a manifold <code>stream</code></p> <p>the benefit is just simplicity - a sequence of individual records is a simpler thing than a sequence of pages of individual records... but there are tradeoffs - sometimes you want to deal with pages of records</p> <p>Oh I see!  Right, yeah, I was just going to consume the channel of returned promises with the doseq I already have, so concatenating them together into one HUGE vector first seemed like a redundant step. i.e. one of the queries I am going to do returns (currently) a little over 13,000 records - I was expecting to grab the results of 14 promises off the channel and \u201cdoseq\u201d each one until the channel was empty</p> <p>I suppose I could consume them off the channel into one big vector, or indeed another channel and then have another consumer running what currently runs inside the doseq on each map / JSON blob that comes out of the channel\u2026  Is that what you mean?</p> <p>so:</p> <p>channel of promises consumer turns vector of maps into another channel of individual maps consumer2 puts maps into DB and ES off second channel</p> <p>i meant another channel, yes</p> <p>possibly even:</p> <p>consumer2 puts maps into DB and onto another channel consumer3 puts maps on third channel into ES</p> <p>(as an aside @maleghast , doing any long-running or blocking processing in a vanilla core.async <code>go</code> block isn't a good idea - there is a fixed-size core.async threadpool which you can exhaust, causing blocking - so you can use https://clojure.github.io/core.async/index.html#clojure.core.async/thread )</p> <p>So if I use thread inside a go block, or instead of a go block..?</p> <p>here is an example</p> <p><code>(async/go   (let [v (async/&lt;! (async/thread (do-blocking-stuff)))]     (do-non-blocking-stuff v))</code></p> <p>something like that</p>"},{"location":"core-async/#long-running-processes","title":"Long running processes","text":"<p>also, beware long-running processes in core.async that expand items with eg. <code>mapcat</code> operations. You can break back pressure that way. (ie. pages on a channel being expanded into multiple events)</p> <p>ooo i haven't come across that problem  what happens ?</p> <p>requires a very specific use case to be a problem, but it\u2019s caught a few people out: https://stackoverflow.com/questions/37953401/where-is-the-memory-leak-when-mapcat-breaks-backpressure-in-core-async</p> <p>Where is the memory leak when mapcat breaks backpressure in core.async? I wrote some core.async code in Clojure and when I ran it it consumed all available memory and failed with an error. It appears that using mapcat in a core.async pipeline breaks back pressure. (Whi...</p> <p>you\u2019re not likely to hit it unless you are using a lot of transforms on your channels, and then its easily worked around, but it can work fine in test, and then blow up in prod with more data/longer running processing</p>"},{"location":"explaining-macros/","title":"Explaining Macros","text":"<p>The macro system allows you to extend the design of the Clojure language, without waiting for the language designers.</p> <p>Expose as much of your API as possible as functions so that they can be stored in hash-maps, mapped over sequences of widgets, negated with complement, juxtaposed with juxt, and so on.</p> <p>Only define your own macros when functions are insufficient or there is a very common abstraction that creates a simpler system.</p>"},{"location":"explaining-macros/#hintclojure-macros-are-quite-unique","title":"Hint::Clojure macros are quite unique","text":"<p>Many languages have macros, although most are more akin to a template systems.</p> <p>Clojure macros are a language within the Clojure language that generate Clojure code when the Clojure Reader parses a macro.  In fact the Clojure Reader will pass the macro to the macro reader which does the expansion.</p>"},{"location":"explaining-macros/#hintevery-macro-adds-maintenance-cost","title":"Hint::Every Macro adds maintenance cost","text":"<p>Adding custom macros adds a higher maintenance cost to a codebase and increased the amount of on-boarding of developers onto a project.</p> <p>Custom macros are additional abstractions to learn when working with a project that are not common across projects in the same way as clojure.core or common libraries.</p>"},{"location":"explaining-macros/#functional-composition-and-macros","title":"Functional composition and Macros","text":"<p>Macros do not compose functionally</p> <p>Macros in Clojure aren't values. They can't be passed as arguments to other functions or macros, can't be returned as the result of computations, and can't be stored in data structures.</p> <p>If macros were values and used as arguments to functions then the compile cycle of Clojure would need to change, otherwise the results of macro expansion wouldn't be known until runtime and could even vary between function calls.</p>"},{"location":"explaining-macros/#wrapping-macros-in-functions-for-composition","title":"Wrapping Macros in functions for composition","text":"<p>It is possible to wrap a macro in a function and then that macro can be used as part of a functionally composed expression.</p> <pre><code>(reduce and [true true false true])\n;;=&gt; RuntimeException\n\n(reduce #(and %1 %2) [true true false true])\n;;=&gt; false\n</code></pre> <p>If you are doing this, then its more probably that a simple function would be a better approach.</p>"},{"location":"io/","title":"IO in Clojure","text":"<p>From http://blog.isaachodes.io/p/clojure-io-p1/</p> <p>The Ins and Outs of Clojure: Part I November 13, 2010</p> <p>(Written about Clojure 1.2.)</p> <p>It is a truth universally acknowledged, that a programmer using Clojure will want to perform IO. Let me help you out (put).</p> <p>I\u2019ll go over some of the basics of IO, focusing on what you can use Clojure to do directly. I\u2019ll move on after the basic introduction, to some of the more interesting and generally useful classes that Java offers, giving a little context for each. In</p> <p>Reading files in is generally one of the first things I want to do when playing with a new language, so I\u2019ll start there. Before I get started though, I should mentioned that in Clojure, strings are always encoded using UTF-16. Generally this saves time and worry, but it\u2019s something to keep in mind should you run into problems on the encoding front. slurp</p> <p>Clojure comes with a handy little function called slurp that takes in a string representing a filename (or, really, pretty much anything; a File, a stream, a byte array, URL, etc) and returns a string containing the contents of your file. It\u2019s pretty handy if you just need to get some information from a file that\u2019s relatively small, and you\u2019ll be parsing it yourself.</p> <p>(slurp \"/home/user/file.txt\") =&gt; \"A little bit\\nof information here.\"</p> <p>A nice thing about slurp is that you can easily build up file paths with str. For example, say you want to output to a file based on information you find at runtime:</p> <p>(slurp (str \"/home/\" username \"/projects/\" filename))</p> <p>But slurp is pretty basic, and once your files get large enough, totally impractical. Nonetheless, it\u2019s a handy function to know about.</p> <p>As a useful and comical aside, the function spit is the counterpart to slurp, except that instead of reading input, spit does output. More on this in a future article, though. line-seq</p> <p>One of my favorite IO functions has got to be line-seq; line-seq takes a reader object (which must implement BufferedReader) and returns a lazy sequence of the lines of the text the reader supplies. This is handy when you\u2019re dealing with files (if this offends you, taking a Unix approach here for now and say that everything is a file) that are too big to merely slurp, but that are \\newline delimited (or CR/LF delimited, if you\u2019re of the Windows persuasion).</p> <p>(use '[clojure.java.io '(reader)]) (take 2   (line-seq (reader \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>Notice how we take 2 from the sequence we get from using line-seq. We can take as much or as little as we need; we won\u2019t be reading much (Clojure will read a bit more than you tell it to in order to get more IO performance, but let\u2019s not worry about that) more than we specify. We can do anything we want with the resulting seq; that\u2019s the beauty of line-seq and the ubiquitous sequence abstraction.</p> <p>Back in the day, Clojurists had to sink a little lower than the clojure.java.io namespace to use line-seq; two Java classes were needed. One of these Java classes is the most wondrous and amazing thing just below the surface of the more elegant and beautiful Clojure code; BufferedReader. Here\u2019s how we used to do it;</p> <p>(import '(java.io FileReader BufferedReader)) (take 2   (line-seq (BufferedReader.               (FileReader. \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>This might give you a better sense of what\u2019s going on when you use reader, though in reality reader is far more complicated than just that: you can trust it to handle a variety of \u201creadable things\u201d and return to you a BufferedReader if possible.</p> <p>FileReader will return a Reader on a file, and BufferedReader takes and buffers a Reader, as you might have extrapolated from the name. Readers are basically just objects upon which a few methods (like read, skip and close) may be enacted and expected to return reasonable results. line-seq essentially reads up until a line-delimiter and returns the read chunk as an element in the sequence it is generating.</p> <p>While on the subject of files, I should probably mentioned the file function, from clojure.java.io. file takes in an arbitrary number of string arguments, and pieces them together into a file hierarchy, returning a File instance. This can come in handy. Rivers? inputStreams? Brooks?</p> <p>Streams are an especially useful class of readers. Oftentimes you\u2019re reading in text; that\u2019s what Readers do. But often you need to read in a stream of bytes; that\u2019s where you need to use clojure.java.io\u2019s input-stream.</p> <p>(use '[clojure.java.io '(reader)]) (def g (input-stream \"t.txt\")) (.read g) =&gt; 105 (.read g) =&gt; 115 (char (.read g)) =&gt; \\space</p> <p>As you can see, instead of getting characters from this file (like we get when we use a reader), we\u2019re getting integer byte values. This can be useful when reading, for example, a media file.</p> <p>In general, strings are always UTF-16, which are 16-bit pieces of data, whereas byte-streams are 8-bit pieces of data. It bears repeating that the stream operators should be used when you\u2019re not dealing with strings: they are not trivially interchangeable, as they might be in other languages where strings are syntactic sugar for byte arrays. RandomAccessFile</p> <p>Finally, let me introduce to you a spectacularly useful Java class. RandomAccessFile is a class which allows you to quickly jump around in a large file, and read bytes from it.</p> <p>(import '(java.io RandomAccessFile)) (def f (RandomAccessFile. \"stuff.txt\" \"r\"))</p> <p>Note the second argument of the constructor, \u201cr\u201d; this indicates that we\u2019re opening the file just for reading. Now that we have f, we can use it to navigate and read the file:</p> <p>(.read f) =&gt; 105 (.length f) =&gt; 2015 ;; this is the number of bytes this file is in length (.skipBytes f 20) (.getFilePointer h) =&gt; 21 ;; the position we're at in the file (.read f) =&gt; 89</p> <p>As you can see, you can jump around (quickly!) through a file, and read from the parts you want, and skip the parts you do not want. The key methods/functions here (among many others that can also be useful; be sure to check the documentation) are read, length, skipBytes, seek and getFilePointer. Closing</p> <p>Every file that is opened should be closed, and what we\u2019ve been doing is a little unsafe. In order to close an open reader/file, we should use the close method on it; in the above example, when you\u2019re done with f, simply execute (.close f) to tell the file system that you\u2019re done with the file. Alternatively, and more idiomatically, you can open your files with the handy with-open binder:</p> <p>(with-open [f (RandomAccessFile. \"stuff.txt\" \"r\")]   (.read f))</p> <p>When you\u2019re done with f, Clojure will close it, and you won\u2019t have to worry one iota about it. Digging Deeper</p> <p>Should slurp and line-seq not be enough for your reading needs (and chances are that, should you code enough in Clojure, they won\u2019t always been), you might want to explore clojure.java.io some more, as well as some of the Java classes (namely, those stemming from Reader and BufferedReader, as well as InputStream and BufferedInputStream) mentioned above. See my previous article on using Java if you\u2019re unfamiliar with using Java.</p> <p>Next up is an introduction to the \u201couts\u201d of Clojure and Java. Stay tuned!</p> <p>I owe a big thank you to Phil Hagelberg for reading over this essay and offering advice. If you don\u2019t already, you should be using his Leiningen for both dependency management and a stress-free development environment.</p> <p>The Ins and Outs of Clojure: Part I November 13, 2010</p> <p>(Written about Clojure 1.2.)</p> <p>It is a truth universally acknowledged, that a programmer using Clojure will want to perform IO. Let me help you out (put).</p> <p>I\u2019ll go over some of the basics of IO, focusing on what you can use Clojure to do directly. I\u2019ll move on after the basic introduction, to some of the more interesting and generally useful classes that Java offers, giving a little context for each. In</p> <p>Reading files in is generally one of the first things I want to do when playing with a new language, so I\u2019ll start there. Before I get started though, I should mentioned that in Clojure, strings are always encoded using UTF-16. Generally this saves time and worry, but it\u2019s something to keep in mind should you run into problems on the encoding front. slurp</p> <p>Clojure comes with a handy little function called slurp that takes in a string representing a filename (or, really, pretty much anything; a File, a stream, a byte array, URL, etc) and returns a string containing the contents of your file. It\u2019s pretty handy if you just need to get some information from a file that\u2019s relatively small, and you\u2019ll be parsing it yourself.</p> <p>(slurp \"/home/account/projects/config.txt\") =&gt; \"A little bit\\nof information here.\"</p> <p>A nice thing about slurp is that you can easily build up file paths with str. For example, say you want to output to a file based on information you find at runtime:</p> <p>(slurp (str \"/home/\" username \"/projects/\" filename))</p> <p>But slurp is pretty basic, and once your files get large enough, totally impractical. Nonetheless, it\u2019s a handy function to know about.</p> <p>As a useful and comical aside, the function spit is the counterpart to slurp, except that instead of reading input, spit does output. More on this in a future article, though. line-seq</p> <p>One of my favorite IO functions has got to be line-seq; line-seq takes a reader object (which must implement BufferedReader) and returns a lazy sequence of the lines of the text the reader supplies. This is handy when you\u2019re dealing with files (if this offends you, taking a Unix approach here for now and say that everything is a file) that are too big to merely slurp, but that are \\newline delimited (or CR/LF delimited, if you\u2019re of the Windows persuasion).</p> <p>(use '[clojure.java.io '(reader)]) (take 2   (line-seq (reader \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>Notice how we take 2 from the sequence we get from using line-seq. We can take as much or as little as we need; we won\u2019t be reading much (Clojure will read a bit more than you tell it to in order to get more IO performance, but let\u2019s not worry about that) more than we specify. We can do anything we want with the resulting seq; that\u2019s the beauty of line-seq and the ubiquitous sequence abstraction.</p> <p>Back in the day, Clojurists had to sink a little lower than the clojure.java.io namespace to use line-seq; two Java classes were needed. One of these Java classes is the most wondrous and amazing thing just below the surface of the more elegant and beautiful Clojure code; BufferedReader. Here\u2019s how we used to do it;</p> <p>(import '(java.io FileReader BufferedReader)) (take 2   (line-seq (BufferedReader.               (FileReader. \"bobby.txt\"))) =&gt; (\"Bobby was a good boy,\" \"and didn't complain too much\")</p> <p>This might give you a better sense of what\u2019s going on when you use reader, though in reality reader is far more complicated than just that: you can trust it to handle a variety of \u201creadable things\u201d and return to you a BufferedReader if possible.</p> <p>FileReader will return a Reader on a file, and BufferedReader takes and buffers a Reader, as you might have extrapolated from the name. Readers are basically just objects upon which a few methods (like read, skip and close) may be enacted and expected to return reasonable results. line-seq essentially reads up until a line-delimiter and returns the read chunk as an element in the sequence it is generating.</p> <p>While on the subject of files, I should probably mentioned the file function, from clojure.java.io. file takes in an arbitrary number of string arguments, and pieces them together into a file hierarchy, returning a File instance. This can come in handy. Rivers? inputStreams? Brooks?</p> <p>Streams are an especially useful class of readers. Oftentimes you\u2019re reading in text; that\u2019s what Readers do. But often you need to read in a stream of bytes; that\u2019s where you need to use clojure.java.io\u2019s input-stream.</p> <p>(use '[clojure.java.io '(reader)]) (def g (input-stream \"t.txt\")) (.read g) =&gt; 105 (.read g) =&gt; 115 (char (.read g)) =&gt; \\space</p> <p>As you can see, instead of getting characters from this file (like we get when we use a reader), we\u2019re getting integer byte values. This can be useful when reading, for example, a media file.</p> <p>In general, strings are always UTF-16, which are 16-bit pieces of data, whereas byte-streams are 8-bit pieces of data. It bears repeating that the stream operators should be used when you\u2019re not dealing with strings: they are not trivially interchangeable, as they might be in other languages where strings are syntactic sugar for byte arrays. RandomAccessFile</p> <p>Finally, let me introduce to you a spectacularly useful Java class. RandomAccessFile is a class which allows you to quickly jump around in a large file, and read bytes from it.</p> <p>(import '(java.io RandomAccessFile)) (def f (RandomAccessFile. \"stuff.txt\" \"r\"))</p> <p>Note the second argument of the constructor, \u201cr\u201d; this indicates that we\u2019re opening the file just for reading. Now that we have f, we can use it to navigate and read the file:</p> <p>(.read f) =&gt; 105 (.length f) =&gt; 2015 ;; this is the number of bytes this file is in length (.skipBytes f 20) (.getFilePointer h) =&gt; 21 ;; the position we're at in the file (.read f) =&gt; 89</p> <p>As you can see, you can jump around (quickly!) through a file, and read from the parts you want, and skip the parts you do not want. The key methods/functions here (among many others that can also be useful; be sure to check the documentation) are read, length, skipBytes, seek and getFilePointer. Closing</p> <p>Every file that is opened should be closed, and what we\u2019ve been doing is a little unsafe. In order to close an open reader/file, we should use the close method on it; in the above example, when you\u2019re done with f, simply execute (.close f) to tell the file system that you\u2019re done with the file. Alternatively, and more idiomatically, you can open your files with the handy with-open binder:</p> <p>(with-open [f (RandomAccessFile. \"stuff.txt\" \"r\")]   (.read f))</p> <p>When you\u2019re done with f, Clojure will close it, and you won\u2019t have to worry one iota about it. Digging Deeper</p> <p>Should slurp and line-seq not be enough for your reading needs (and chances are that, should you code enough in Clojure, they won\u2019t always been), you might want to explore clojure.java.io some more, as well as some of the Java classes (namely, those stemming from Reader and BufferedReader, as well as InputStream and BufferedInputStream) mentioned above. See my previous article on using Java if you\u2019re unfamiliar with using Java.</p> <p>Next up is an introduction to the \u201couts\u201d of Clojure and Java. Stay tuned!</p> <p>I owe a big thank you to Phil Hagelberg for reading over this essay and offering advice. If you don\u2019t already, you should be using his Leiningen for both dependency management and a stress-free development environment.</p>"},{"location":"lazy-evaluation/","title":"Lazy evaluation","text":"<p><code>repeat</code></p>"},{"location":"testing-in-clojure/","title":"Testing in clojure","text":"<p>My recommended Clojure testing setup</p> <p>kaocha test runner in watch mode</p> <p>Occasionally, either on Stack Overflow or in the Clojurians Slack group, someone will ask what tools they should use to test Clojure code. Below is what I would currently recommend. I\u2019ve come to this recommendation through observing teams using a variety of testing tools and through my own use them.</p> <p>Use clojure.test with humane-test-output and lein-test-refresh.</p> <p>Use clojure.test</p> <p>clojure.test is ubiquitous and not a big departure from other languages' testing libraries. It has its warts but your team will be able to understand it quickly and will be able to write maintainable tests.</p> <p>Use humane-test-output</p> <p>You should use clojure.test with humane-test-output. Together they provide a testing library that has minimal additional syntax and good test failure reporting.</p> <p>Use lein-test-refresh</p> <p>If you\u2019re not using a tool that reloads and reruns your tests on file changes then you are wasting your time. The delay between changing code and seeing test results is drastically reduced by using a tool like lein-test-refresh. Nearly everyone I know who tries adding lein-test-refresh to their testing toolbox continues to use it. Many of these converts were not newcomers to Clojure either, they had years of experience and had already developed workflows that worked for them.</p> <p>Use lein-test-refresh\u2019s advanced features</p> <p>lein-test-refresh makes development better even if you don\u2019t change any of its settings. It gets even better if you use some of its advanced features.</p> <p>Below is a stripped down version of my ~/.lein/profiles.clj. The :test-refresh key points towards my recommended lein-test-refresh settings.</p> <p>{:user {:dependencies [[pjstadig/humane-test-output \"0.8.0\"]]         :injections [(require 'pjstadig.humane-test-output)                      (pjstadig.humane-test-output/activate!)]         :plugins [[[com.jakemccrary/lein-test-refresh \"0.16.0\"]]]         :test-refresh {:notify-command [\"terminal-notifier\" \"-title\" \"Tests\" \"-message\"]                        :quiet true                        :changes-only true}}}</p> <p>These settings turn on notifications when my tests finish running (:notify-command setting), make clojure.test\u2019s output less verbose (:quiet true), and only run tests in namespaces affected by the previous code change (:changes-only true). These three settings give me the quickest feedback possible and free me from having the terminal running lein test-refresh visible.</p> <p>Quick feedback lets you make changes faster. If you\u2019re going to write tests, and you should write tests, having them run quickly is powerful. After years of writing Clojure, this is my current go-to for testing Clojure code and getting extremely fast feedback.</p> <p>I use test-refresh every day. Frankly I'm not sure how one can program effectively without it. I especially like being able to control the notifications</p>"},{"location":"alternative-tools/","title":"Alternative Tools","text":""},{"location":"alternative-tools/clojure-cli/basic-repl/","title":"Basic Terminal REPL UI","text":"<p>The <code>clojure</code> command will start a REPL by default or if given the <code>--repl</code> or <code>-r</code> argument.  The basic repl does not provide history of commands.</p> <p><code>clj</code> is a script that wraps the <code>clojure</code> command and requires <code>rlwrap</code>, an external readline command, to navigate REPL history via the Up and Down keys.</p> <p>Use <code>clj</code> when you want to run a repl (or preferably use rebel readline instead) and <code>clojure</code> for everything else.</p> <p>Rebel Rich Terminal UI</p> <p>rebel readline is a terminal REPL UI that provides interactive help, function autocomplete, signature prompts and many other features to provide a very rich REPL experience.</p> <p> Practicalli Clojure CLI Config includes the <code>-M:repl/rebel</code> alias to run rebel readline REPL.</p> <p><code>clj</code> command in a terminal window starts a Clojure REPL and shows the version of Clojure used.  The command does not need to be in a directory containing a Clojure project.</p> <pre><code>clj\n</code></pre> <p>Type in a Clojure expression at the <code>=&gt; user</code> REPL prompt and press Enter to see the result</p> <p>Ctrl+d to exit the REPL</p> <p></p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/","title":"Clojure Automation Aproaches","text":"<p>Leiningen, Clojure CLI tools and Boot are different approaches to Clojure project configuration.  Regardless of the tool used, the Clojure code in the project remains the same.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#clojure-cli-tools-overview","title":"Clojure CLI tools overview","text":"<p>Clojure CLI tools takes a very simple approach, focusing on running a REPL process, Clojure programs via clojure main and specific functions via clojure exec.  With the Clojure exec approach any function can be called as the entry point to running an application or tool written in Clojure.</p> <p>CLI tools can use both Maven and Git repositories for dependency management.  Code from a Git repository dependency can be used without packaging it into a library (Java jar file), simplifying the use of libraries under active development.</p> <p>Clojure CLI tools provides a comprehensive set of features via community tools.  These community tools are provided via aliases in the user level configuration for all projects (e.g. practicalli/clojure-deps-edn) or an alias for a specific project <code>deps.edn</code> configuration.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#leiningen-overview","title":"Leiningen overview","text":"<p>Leiningen is a feature rich tool which is simple to get started with a plugin extension to add more functionality.  Leiningen does use more resources as it starts a Java Virtual machine to run itself and another to run the application.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#boot-overview","title":"Boot overview","text":"<p>Boot runs tasks written in Clojure on the command line, providing a flexible way to work with projects.  However, this approach does require expertise with Clojure and  Clojure scripts to work with projects.</p> <p>Clojure code is the same which ever approach used</p> <p>The Clojure code for the project will be the same regardless of which tool is used to configure and manage the Clojure project.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#configuration","title":"Configuration","text":"Tool Project Config User Config Extension Clojure CLI tools deps.edn hash-map merged with user config <code>$XDG_HOME_CONFIG/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code> aliases in project and user deps.edn Leiningen project.clj and <code>defproject</code> macro ~/.lein/profiles.clj Leiningen specific plugin Boot build.boot with <code>deftask</code>, <code>task-options!</code>, <code>set-env!</code> Write the tasks required in Clojure Clojure CLILeiningenBoot <p>Clojure CLI tools are configured with an EDN data structure, i.e. a hash-map of key-value pairs.  As this is a Clojure data structure its much easier to parse and should be very familiar to Clojure developers.</p> <p>Leiningen projects are configured with a <code>project.clj</code> file which contains a <code>defproject</code> macro with a great many options.  The Leiningen tutorial explains the options in detail.  A sample project.clj contains examples of using each of this options.</p> <p>For most projects all the configuration resides in the project.clj file.  Exceptions to this include figwheel-main, which also adds it own EDN configuration and EDN build configuration files.</p> <p>Leiningen also has a user level configuration</p> <p><code>build.boot</code> is a file containing Clojure code that defines the tasks for using your project.</p>"},{"location":"alternative-tools/clojure-cli/compare-with-leiningen/#extending-the-tools","title":"Extending the tools","text":"Clojure CLILeiningenBoot <p>Clojure CLI tools has been designed for a very specific role, to provide a lightweight wrapper over running Clojure programs and via tools.deps managing dependencies from Maven and Git repositories.</p> <p>The projects that extend Clojure CLI tools are self-contained libraries and tools, so are not tied to any one particular tool.  Any general tools written for Clojure should work with Clojure CLI tools by calling their main function (clojure main) or a specifically named function (clojure exec)</p> <p>Leiningen plugin extension was the main way to extend the functionality of Leiningen (or getting pull requests accepted to the Leiningen projects).</p> <p>Although there are several plugins that were widely adopted, some plugins eventually caused more confusion than benefit or were simply trivial and in the main plugins seem to have become less important to the Clojure community.</p> <p>One of the limitations of Leiningnen plugin mechanism was not being able to exclude any configuration in a users <code>.lein/profiles.clj</code> file, so there was greater potential for conflict.</p> <p>The recommended way to extend Leiningen is to not write plugins, but to include aliases that define a qualified function to run when that alias is used with the Leiningen command.</p> <p>Write clojure to define scripts to run with boot projects.</p> <p>Babashka for Clojure scripting</p> <p>Babashka is an approach to writing bash-style scripts using the Clojure language.  Babashka bundles additional libraries to support common tasks</p>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/","title":"Evaluating an expression with Clojure CLI tools","text":"<p>An expression is a piece of Clojure code that can be evaluated and return a result</p> <p>This expression calls the <code>+</code> function with the arguments <code>1 2 3 4 5</code>.  As this code works, we get a result.</p> <pre><code>(+ 1 2 3 4 5)\n</code></pre> <p>Using the <code>-e</code> option an expression can be passed to the Clojure CLI tools and a value returned</p> <pre><code>clojure -e (+ 1 2 3 4 5)\n</code></pre>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/#expressions-returning-nil","title":"Expressions returning <code>nil</code>","text":"<p>If the expressing used returns a value of <code>nil</code>, a legal value in Clojure, then no result is printed out.</p>"},{"location":"alternative-tools/clojure-cli/evaluate-an-expression/#when-to-use-this","title":"When to use this?","text":"<p><code>clojure -e</code> is a quick way to see what an expression does without having to set anything up (although starting a REPL is very little extra effort).</p> <p>Using the <code>-e</code> option is useful for running simple scripts written in Clojure, especially on servers and remote environments.</p> <p>The lack of return value for nil is very useful when using Clojure CLI tools to evaluate Clojure code within another script.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/","title":"Set namespace on REPL startup","text":"<p>The REPL process does not evaluate project code on start-up.  If it did and that code had a error, it could prevent the REPL from starting.</p> <p>The common approach is to require the main namespace for the project, making the functions in that namespace available.  This will also make available functions from those namespaces.</p> <p>Switching to a specific namespace in the REPL allows calling functions by name, without the fully qualified name.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-via-the-command-line","title":"Set namespace via the command line","text":"<p>To require and switch to a namespace on startup, use the <code>clojure</code> or <code>clj</code> commands with the --eval option to run the specific commands.  The --repl option will ensure the repl starts.</p> <pre><code>clj --eval \"(require 'practicalli.random-clojure-core-function)\" --eval \"(in-ns 'practicalli.random-clojure-core-function)\" --repl\n</code></pre> <p><code>-r</code> or <code>(clojure.main/repl)</code> are the same as using the <code>--repl</code> option</p> <pre><code>clj -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly 'foo.bar))\" -r\nclj -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly 'foo.bar)) (clojure.main/repl)\"\n</code></pre>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-with-rebel-readline","title":"Set namespace with Rebel Readline","text":"<p>Set the namespace using Rebel Readline alias from  Practicalli Clojure CLI Config</p> <pre><code>clj -M:lib/rebel -e \"(ns foo.bar) (alter-var-root #'*ns* (constantly (find-ns 'foo.bar)))\" -m rebel-readline.main\n\n#object[clojure.lang.Namespace 0x46cf05f7 \"foo.bar\"]\n[Rebel readline] Type :repl/help for online help info\nfoo.bar=&gt;\n</code></pre> <p>The <code>:lib/rebel</code> alias adds the rebel library as a dependency without calling clojure main on the rebel namespace.  <code>alter-var-root</code> sets the namespace. The <code>-m</code> flag defines the namespace which Clojure main will run the <code>-main</code> function from, starting the rebel UI on the command line.</p> <p>The <code>--eval</code> approach will be blocked if used with aliases that set the main namespace, such as <code>:repl/rebel</code>.</p>"},{"location":"alternative-tools/clojure-cli/set-namespace-on-repl-startup/#set-namespace-using-an-editor","title":"Set namespace using an editor","text":"<p>It is not necessary to set the namespace when evaluating code in a Clojure aware editor.  Expressions are evaluated within the scope of the namespace in which they are defined.</p> <p>Using an editor to evaluate Clojure is much simpler and quicker than using a command line REPL, especially when working with Clojure projects with more than one namespace.</p>"},{"location":"alternative-tools/data-inspector/reveal/","title":"Reveal REPL with visual data browser","text":"<p>Reveal provides a REPL with a connected visual data explorer.  Reveal can also be used as a <code>tap&gt;</code> target, visualizing data added to a <code>tap&gt;</code> (an elegant approach compared to print statements).</p> <p>Reveal describes itself as a read evaluate visualize loop tool proving extra tools to explore data in Clojure visually.  The extensive documentation shows the many ways to use Reveal.</p> <p>Use Reveal with a terminal REPL or a Clojure editor that uses nrepl such as Emacs Cider and Spacemacs.  Reveal can be added as a tap source to any running REPL, eg. using Reveal with Rebel Readline.</p> <p> </p> REPL Terminal UInrepl Editors <p> Practicalli Clojure CLI Config contains the <code>:inspect/reveal</code> alias to run Reveal REPL in a terminal with the Reveal UI along-side.</p> <p>Open a terminal and run the command:</p> <pre><code>clojure -M:inspect/reveal\n</code></pre> <p>Use the <code>clj</code> command if the <code>rlwrap</code> binary is available</p> <p>Write Clojure code as normal in the REPL and result are also sent to the Reveal data browser window.</p> <p>The extensive documentation shows the many ways to use Reveal.</p> <p>Start reveal with an nREPL server to allow connection from a Clojure aware editor</p> Practicalli Clojure CLI ConfigAlias Definition <p><code>:inspect/reveal-nrepl</code> alias provided by  Practicalli Clojure CLI Config runs a Reveal repl with data browser and nrepl server, allowing connections from Clojure aware editors such as Emacs CIDER and VSCode Calva.</p> <p><code>:inspect/reveal-light-nrepl</code> does the same and uses a light them with Ubuntu Mono 32 point font (good for demos, HiDPI screens)</p> <p>Add the following aliases to your user level <code>~/.clojure/deps.edn</code> configuration to make reveal available to all projects.</p> <p>Plain nrepl server with Reveal.</p> <p><pre><code>  :inspect/reveal-nrepl\n  {:extra-deps {vlaaad/reveal {:mvn/version \"1.1.159\"}\n                nrepl/nrepl   {:mvn/version \"0.8.3\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[vlaaad.reveal.nrepl/middleware]\"]}\n</code></pre> CIDER specific nrepl connection with the Cider middleware</p> <pre><code>  :inspect/reveal-nrepl-cider\n  {:extra-deps {vlaaad/reveal                 {:mvn/version \"1.1.159\"}\n                nrepl/nrepl                   {:mvn/version \"0.8.3\"}\n                cider/cider-nrepl             {:mvn/version \"0.25.4\"}\n                refactor-nrepl/refactor-nrepl {:mvn/version \"2.5.0\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[vlaaad.reveal.nrepl/middleware,refactor-nrepl.middleware/wrap-refactor,cider.nrepl/cider-middleware]\"]}\n</code></pre> <p>Start a Reveal REPL with nrepl server</p> <pre><code>clojure -M:inspect/reveal-nrepl\n</code></pre> <p>Connect to the Reveal repl from a Clojure aware editor, e.g <code>cider-connect</code></p>"},{"location":"alternative-tools/data-inspector/reveal/#using-reveal-with-cider-jack-in","title":"Using Reveal with Cider Jack-in","text":"<p><code>C-u cider-jack-in-clj</code> in CIDER to start a reveal REPL  (<code>SPC u , '</code> in Spacemacs)</p> <p>Edit the jack-in command by deleting the all the configuration after the <code>clojure</code> command and add the alias <pre><code>clojure -M:inspect/reveal-nrepl-cider\n</code></pre></p> <p><code>:inspect/reveal-nrepl-cider</code> is a light version of the above.</p>"},{"location":"alternative-tools/data-inspector/reveal/#cider-jack-in-with-reveal-using-a-dir-localsel","title":"Cider jack-in with reveal using a .dir-locals.el","text":"<p>Add a <code>.dir-locals.el</code> file to the root of the Clojure project. The <code>.dir-locals.el</code> configuration adds the <code>:inspect/reveal-nrepl-cider</code> via <code>cider-clojure-cli-aliases</code> and all other automatically injected configuration is disabled to prevent those dependencies over-riding the alias.</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":inspect/reveal-nrepl-cider\")\n                  (cider-jack-in-dependencies . nil)\n                  (cider-jack-in-nrepl-middlewares . nil)\n                  (cider-jack-in-lein-plugins . nil)\n                  (cider-clojure-cli-parameters . \"\"))))\n</code></pre> <p>Ensure the <code>.dir-locals.el</code> file is loaded by using <code>revert-buffer</code> on any open Clojure file from the project.</p> <p><code>cider-jack-in-clj</code> should now start the Reveal REPL and send evaluations from Cider to the Reveal visualization UI.</p>"},{"location":"alternative-tools/data-inspector/reveal/#reveal-with-rebel-and-tap","title":"Reveal with Rebel and <code>tap&gt;</code>","text":"<p>Reveal can be used as a <code>tap&gt;</code> target with the Rebel REPL, launching the Reveal data browser when added as a tap&gt; target.</p> <p>Start Rebel REPL with Reveal library as a dependency</p> <pre><code>clojure -M:repl-reveal:repl/rebel\n</code></pre> <p>Add reveal as a tap target that will receive all data from <code>tap&gt;</code> function calls</p> <pre><code>(add-tap ((requiring-resolve 'vlaaad.reveal/ui)))\n</code></pre> <p>A reveal window opens and receives all <code>tap&gt;</code> values while the REPL is running.</p> <pre><code>(tap&gt; [1 2 3 4 5])\n(tap&gt; {:name \"Jenny\" :skill \"Clojure\"})\n(tap&gt; (zipmap [:a :b :c] [1 2 3 4]))\n</code></pre>"},{"location":"alternative-tools/data-inspector/reveal/#atom-and-tapped-value","title":"Atom and Tapped value","text":"<p>Create an atom for debugging purposes</p> <pre><code>(def debug-state (atom nil))\n(add-tap #(reset! debug-state %))\n</code></pre> <p>Use <code>tap&gt;</code> to capture intermediate values in the middle of code that requires debugging, inspecting or watching the atom value (deref the atom and watch:latest or watch:all).  This approach complements an editor debugging process</p>"},{"location":"alternative-tools/data-inspector/reveal/#tracking-state-with-an-atom","title":"Tracking state with an atom","text":"<p>Define the state as an atom, the state being a simple value in this case</p> <pre><code>(def state (atom 24))\n</code></pre> <p>Select the reference created for the state in the Revel browser.</p> <p><code>SPACE</code> or <code>ENTER</code> to open the menu and select <code>Deref</code>.  A tab opens with the value of the atom.</p> <p><code>SPACE</code> or <code>ENTER</code> with the value selected and select <code>Watch:all</code>.</p> <p>In the REPL, update the value of the state atom.</p> <pre><code>(swap! state * 12)\n</code></pre> <p>The new value of the state atom is shown in the Reveal data browser.  Each Clojure expressions evaluated that affects the state atom will be displayed in the Reveal browser.</p>"},{"location":"alternative-tools/data-inspector/reveal/#running-different-types-of-repl","title":"Running different types of repl","text":"<p>Using Clojure exec <code>-X</code> flag, the default repl function can be over-ridden on the command line, supplying the <code>io-prepl</code> or <code>remote-prepl</code> functions.</p> <ul> <li><code>clojure -X:inspect/reveal io-prepl :title '\"I am a prepl repl\"</code></li> <li><code>clojure -X:inspect/reveal remote-prepl :title '\"I am a remote prepl repl\"'</code></li> </ul>"},{"location":"alternative-tools/data-inspector/reveal/#configure-theme-font","title":"Configure theme &amp; font","text":"<p>Add a custom theme and font via the <code>-J</code> command line option or create an alias using <code>:inspect/reveal-light</code> as an example.</p> <pre><code>clojure -M:inspect/reveal -J-Dvlaaad.reveal.prefs='{:theme :light :font-family \"Ubuntu Mono\" :font-size 32}'\n</code></pre>"},{"location":"alternative-tools/data-inspector/reveal/#rebel-readline-reveal-add-reveal-as-tap-source","title":"Rebel Readline &amp; Reveal: Add Reveal as tap&gt; source","text":"<p>Evaluate <code>(add-tap ((requiring-resolve 'vlaaad.reveal/ui)))</code> when using Rebel Readline to add Reveal as a tap source, showing <code>(tap&gt; ,,,)</code> expressions in the reveal window, eg. <code>(tap&gt; (map inc [1 2 3 4 5]))</code>.</p>"},{"location":"alternative-tools/leiningen/","title":"Leiningen build automation tool","text":"<p>Leiningen will help you create, build and deploy your Clojure projects.</p> <p>Practicalli recommends using Clojure CLI</p> <p>For new project, Clojure CLI is recommended as it requires fewer resources and enables a more customisable approach to configuring project and running tools to support Clojure development.</p>"},{"location":"alternative-tools/leiningen/#install-leiningen","title":"Install Leiningen","text":"<p>Install the Leiningen tool using the specific instructions for your Operating System</p> <p>{% tabs first=\"Linux\", second=\"Homebrew\", third=\"GitBash\", forth=\"Chocolatey\", fifth=\"Windows Manual\" %}</p> LinuxHomebrewGitBashChocolateyWindows <p>Download the lein script to your local <code>bin</code> directory.  Then make the <code>lein</code> script executable and run <code>lein</code> to download the full version.</p> <p><pre><code>mkdir ~/bin\ncurl https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein &gt; ~/bin/lein\nchmod u+x ~/bin/lein\nlein\n</code></pre> If the command <code>lein</code> is not found, run <code>source ~/.bashrc</code> to ensure your <code>bin</code> directory is on the path.</p> <p>If you have Homebrew installed, run the following command in a terminal window.</p> <pre><code>brew install leiningen\n</code></pre> <p>GitBash allows you to use the Linux <code>lein</code> script, which may have less issues when installing.</p> <p>Create a directory called <code>C:\\Users\\your-user-name\\AppData\\Local\\Programs\\Leiningen</code></p> <p>Download the <code>lein</code> file and save it to the above directory</p> <p>Open <code>Environment variables for your account</code> and add the directory to your path</p> <p>Open a command window and run the command: <code>lein</code></p> <p>The full version of Leiningen will be downloaded and Leiningen is ready to use.</p> <p>If you have Chocolatey installed, add the Leiningen package by running the following command in a terminal window.</p> <pre><code>choco install lein\n</code></pre> <p>Create a directory called <code>C:\\Users\\your-user-name\\AppData\\Local\\Programs\\Leiningen</code></p> <p>Download the <code>lein.bat</code> file and save it to the above directory</p> <p>Open <code>Environment variables for your account</code> and add the directory to your path</p> <p>Open a command window and run the command: <code>lein.bat</code></p> <p>The full version of Leiningen will be downloaded and Leiningen is ready to use.</p>"},{"location":"alternative-tools/leiningen/#run-leiningen","title":"Run Leiningen","text":"<p>Check Leiningen is working by running <code>lein</code> command in a terminal</p> <pre><code>lein help\n</code></pre> <p>If a list of Leiningen commands is shown then it is working correctly.</p>"},{"location":"alternative-tools/leiningen/#create-project","title":"Create project","text":"<p>Create a new Clojure project with Leiningen using the <code>new</code> task</p> <pre><code>lein new template-name domain/project-name\n</code></pre> <p>Built-in templates include <code>app</code> and <code>lib</code></p> <p>Create a new project called playground</p> <p>Open a terminal window and in a directory where you usually keep your projects, run the following command <pre><code>lein new app practicalli/playground\n</code></pre> A new directory will be created called <code>playground</code> with a <code>src/practicalli/playground.clj</code></p>"},{"location":"alternative-tools/leiningen/#unit-testing","title":"Unit Testing","text":"<p>Leiningen automatically includes the <code>test</code> directory when running, so no additional configuration is required if all tests reside inside the <code>test</code> directory.</p> <p>Run all the tests saved to file:</p> <pre><code>lein test\n</code></pre> <p>Run just the unit tests in a specific namepsace.</p> <pre><code>lein test :only domain.namespace-test\n</code></pre>"},{"location":"alternative-tools/leiningen/#test-plugins","title":"Test Plugins","text":"<p>The following Leiningen plugins watch the file system and will run tests when a file change is detected in the project files.</p> <ul> <li>lein-test-refresh</li> <li>lein-auto</li> </ul>"},{"location":"alternative-tools/leiningen/#configure-test-paths","title":"Configure test paths","text":"<p><code>:test-paths</code> added as a top level key to the <code>defproject</code> configuration in the <code>project.clj</code> file will configure specific paths for tests</p> <p>For example, if the tests are defined under <code>project-name/clj/tests</code> then the project.clj file would look as follows:</p> <pre><code>(defproject my-project \"0.5.0-SNAPSHOT\"\n  :description \"A project for doing things.\"\n  :license \"Creative Commons Zero\"\n  :url \"http://github.com/practicalli/my-project\"\n\n  :dependencies [[org.clojure/clojure \"1.10.1\"]]\n  :test-paths   [\"clj/test\" \"src/test/clojure\"]\n  :plugins      [[lein-auto \"0.1.3\"]])\n</code></pre> <p><code>:source-paths</code> can also be used to define the location of the source code files in the same manner.</p>"},{"location":"assets/images/social/","title":"Social Cards","text":"<p>Social Cards are visual previews of the website that are included when sending links via social media platforms.</p> <p>Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in <code>mkdocs.yml</code></p> <p>Generated images are stored in this directory.</p>"},{"location":"automation/","title":"Automation","text":"<p>Automation tools can provide a consistent command line interface across a wide range of projects.</p> <p>Whilst the Clojure CLI is a very extensible tool that flexibility can also add some complexity to its command line interface.</p> <p>Automation tools abstract the command line to provide a consistent and simple user experience whilst keeping underlying flexibility.</p> <p>Practicalli recommends make</p> <p>A Makefile is not reliant on programming language knowledge so has no barrier to those who are unfamiliar with the Clojure language.</p> <p>Make is useful when working with mixed language teams to create a unified tool and command line across a wide range of projects.</p>"},{"location":"automation/#automation-tooling","title":"Automation tooling","text":"<ul> <li>Make - ubiquitous task automation tool, programming language agnostic</li> <li>Shell Scripts</li> <li>Babashka - create task automation tool with Clojure</li> </ul>"},{"location":"automation/#make","title":"Make","text":"<p>Make is very simple to use and has a long history as a build tool and wider task automation tool.</p> <p>Task are defined in a <code>Makefile</code> and task can depend on each other. Any commands or combination of commands that run on the command line can be used as make tasks.</p> <p>make provides tab completion of tasks defined in the Makefile without additional configuration.</p> <p><code>make</code> is available for all operating systems.</p> <p>Practicalli Project Templates include Makefile</p> <p>Creating new projects with <code>:project/create</code> and Practicalli Project Templates provide a Makefile with a wide range of common tasks for Clojure development. </p>"},{"location":"automation/#shell-scripts","title":"Shell Scripts","text":"<p>Shell scripts provide a very common way to create a relatively ubiquitous approach to running tools, even across multiple Shell implementations (Bash, Zsh, fish, etc.) and operating systems.</p> <p>Shell scripting language is very powerful especially for manipulation of the operating system, although scripts require development and maintenance.</p>"},{"location":"automation/#babashka","title":"Babashka","text":"<p>Write automation scripts with Clojure code using the Babashka task runner</p> <p>Babashka can use a wide range of Clojure functions and libraries, although as a general script tool then additional coding and maintenance may be reqiured compared to a dedicated tool.</p> <p>Babashka task runner</p>"},{"location":"automation/make/","title":"Make","text":"<p> practicalli/dotfiles Makefile</p> <p>GNU Make provide a simple and consistent way to run any development task for Clojure &amp; ClojureScript projects (or any other languages).</p> <p>Wrap any combination of tools (building, linting, formatting, testing) with Make targets for a simple command line interface.</p> <p>Make supports tab completion making tasks discoverable.</p> <p>All that is required is a <code>Makefile</code> in the root of the project</p>"},{"location":"automation/make/#gnu-make-overview","title":"GNU Make overview","text":"<p>GNU Make is a language agnostic build automation tool which has been an integral part of building Linux/Unix operating system code and applications for decades, providing a consistent way to configure, compile and deploy code for all projects.</p> <p>A <code>Makefile</code> defines targets called via the <code>make</code> command. Each target can run one or more commands.  Targets can be dependent on other targets,  e.g the <code>dist</code> target that builds a project can be dependent on <code>deps</code> &amp; <code>test</code> targets.</p> <p>GNU Make is available on all Linux/Unix based operating systems (and Windows via chocolatey or nmake).</p> <p>Practicalli also uses <code>make</code> to configure and build the latest versions of Emacs and other Linux open source software</p>"},{"location":"automation/make/#defining-tasks","title":"Defining tasks","text":"<p>Create a <code>Makefile</code> in the root of a project and define a target by typing a suitable name followed by a <code>:</code> character, e.g. <code>test:</code></p> <p>Insert a tab on the next line and type a command to be called.  Further commands can be added on new lines so long as each line is tab indented.</p> <p>The <code>repl</code> target prints out an information message and then uses the Clojure CLI with aliases from practicalli/clojure-deps-edn to run a Clojure REPL process with a rich terminal UI (Rebel Readline)</p> <pre><code>repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:dev/env:test/env:repl/rebel\n</code></pre>"},{"location":"automation/make/#common-target-naming","title":"Common target naming","text":"<p>Targets used across Practicalli projects follow the make standard targets for users</p> <p><code>all</code> , <code>test-ci</code> , <code>deps</code> and <code>dist</code> targets are recommended for use with a CI deployment pipeline and builder stage when using Docker.</p> <ul> <li><code>all</code>  calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean</li> <li><code>deps</code> download library dependencies (depend on <code>deps.edn</code> file)</li> <li><code>dist</code> create a distribution tar file for this program or zip deployment package for AWS Lambda</li> <li><code>lint</code> run lint tools to check code quality  - e.g MegaLinter which provides a wide range of tools</li> <li><code>format-check</code> report format and style issues for a specific programming language</li> <li><code>format-fix</code> update source code files if there are format and style issues for a specific programming language</li> <li><code>pre-commit</code> run unit tests and code quality targets before considering a Git commit</li> <li><code>repl</code> run an interactive run-time environment for the programming language</li> <li><code>test-unit</code> run all unit tests</li> <li><code>test-ci</code> test running in CI build (optionally focus on integration testing)</li> <li><code>clean</code> remove files created by any of the commands from other targets (i.e. ensure a clean build each time)</li> </ul> <p>practicalli/dotfiles/Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.</p>"},{"location":"automation/make/#target-dependencies","title":"Target dependencies","text":"<p>A <code>Makefile</code> target can depend on either a file name or another target in the <code>Makefile</code>.</p> <p>The all target typically depends on several <code>Makefile</code> targets to test, compile and package a service.  Add the names of the targets this target depends upon</p> <pre><code>all: deps test-ci dist clean\n</code></pre> <p>Add the filename of a file after the name of the target, to depend on if that file has changed.  If the file has not changed since make was last run then the task will not run again.</p> <p>Clojure CLI Example: If the <code>deps</code> target depends on <code>deps.edn</code> and the file has not changed since last run, the deps target will not run again.</p>"},{"location":"automation/make/#deps-target-depend-on-a-file","title":"deps target - depend on a file","text":"<p>The deps target would use Clojure CLI or Leiningen to download dependencies.</p> <p>Configuring the <code>deps</code> target to depend on <code>deps.edn</code> or <code>project.clj</code> file, then if the file has not changed the deps will not run again.</p> <p>A Clojure CLI example depends on the <code>deps.edn</code> file that defines all the library dependencies for the project, tools for testing and packaging the Clojure service.  The <code>-P</code> flag is the prepare option, a dry run that only downloads the dependencies for the given tasks.</p> <pre><code>deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download libraries to test and build the service ---------)\n    clojure -P -X:test/env:package/uberjar\n</code></pre> <p><code>:test/env</code> adds libraries to run Kaocha and libraries used to run unit tests.  <code>:package/uberjar</code> runs a tool that creates an uberjar.</p>"},{"location":"automation/make/#clean-target-hiding-command-errors","title":"Clean target - hiding command errors","text":"<p>The clean target should remove files and directories created by the build (compile) process, to ensure a consistent approach to building each time.</p> <p>On Linux / Unix systems files can be deleted with the <code>rm</code> command using <code>-r</code> for recursively deleting a directory and its contents. <code>-f</code> forces the deleting of files and directories, otherwise a prompt for confirmation of the delete may be shown.</p> <p><code>-</code> before a command  instructs <code>make</code> to ignore an error code, useful if the files to be deleted did not exist (i.e. the build failed part way through and not all files were created).</p> <pre><code># `-` before the command ignores any errors returned\nclean:\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n</code></pre>"},{"location":"automation/make/#megalinter-target-simplifying-a-command","title":"MegaLinter target - simplifying a command","text":"<p>The <code>lint</code> target is an example of how the <code>Makefile</code> simplifies the command line interface.</p> <p><code>lint:</code> target is used to call the MegaLinter runner, avoiding the need to remember the common options passed when calling MegaLinter command line tool, <code>mega-linter-runner</code></p> <p>The Java flavor of MegaLinter is less than 2Gb image (full MegaLinter image is 8Gb) and contains all the tools for a Clojure project.  The flavor can only be set via a command line option, so the make file ensures that option is always used and the full MegaLinter docker image is not downloaded by mistake.</p> <p>When MegaLinter is configured to generate reports (default), <code>lint-clean:</code> target is used to clean those reports.</p> <pre><code># Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n\nlint-clean:\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n</code></pre>"},{"location":"automation/make/#enhancing-make-output","title":"Enhancing make output","text":"<p>The <code>info</code> message is used with each target to enhances the readability of the make output, especially when multiple targets and commands are involved, or if commands are generating excessive output to standard out.</p> <pre><code> test:\n    $(info --------- Runner for unit tests ---------)\n    ./bin/test\n</code></pre> <p></p>"},{"location":"automation/make/#avoiding-file-name-collisions","title":"Avoiding file name collisions","text":"<p>Although unlikely, if a filename in the root of a project has the same name as a <code>Makefile</code> target, it can be used instead of running the targets command</p> <p><code>.PHONY:</code> defines the names of targets in the <code>Makefile</code> to avoid name clashes</p> <pre><code>.PHONY: all lint deps test test-ci dist clean\n</code></pre> <p>phony - MakefileTutorial</p>"},{"location":"automation/make/#halt-on-error","title":"Halt on error","text":"<p><code>.DELETE_ON_ERROR:</code> halts any further commands if a command returns non-zero exit status.  Useful as short-circuit to stop tasks when further work is not valuable, e.g. if tests fail then it may not be valuable to build the Clojure project.</p> <pre><code>.DELETE_ON_ERROR:\nall: deps test-ci dist clean\n</code></pre> <p>delete_on_error - MakefileTutorial</p>"},{"location":"automation/make/#references","title":"References","text":"<p>Makefile Tutorial by Example practicalli/dotfiles Makefile</p>"},{"location":"automation/make/#summary","title":"Summary","text":"<p>A <code>Makefile</code> can simplify the command line interface for any task with a Clojure project (or any other language and tooling).</p> <p>Using the same target names across all projects reduces the cognitive load for driving any project.</p>"},{"location":"clojure-cli/","title":"Clojure CLI","text":"Learn by doing <p>To learn Clojure CLI by doing, jump to Terminal REPL or Clojure project sections to start using the Clojure CLI</p> <p>Clojure CLI (command line interface) is the latest approach to working with Clojure projects, libraries and tools. Clojure CLI focuses on:</p> <ul> <li>running Clojure code (applications and tools)</li> <li>starting a REPL process (Read-Eval-Print Loop) for interactive development with a Clojure editor or a command line REPL UI.</li> <li>managing dependencies (tools.deps) -downloading from Maven and Git repositories</li> <li>building Clojure projects (using tools.build) to create deployable Clojure services</li> </ul> <p> Practicalli Clojure CLI Config extends the feautres of Clojure CLI, defining aliases that add community libraries and tools.</p> <p> </p> Video commands dated but concepts remain valid"},{"location":"clojure-cli/#common-tasks-for-clojure-development","title":"Common tasks for Clojure development","text":"<p>The Clojure CLI has several built-in tasks.  Additional tasks are provided via aliases that include libraries and tools from the Clojure community, e.g.  Practicalli Clojure CLI Config</p> <p>REPL Reloaded</p> <p><code>clojure -M:repl/reloaded</code> runs a rich terminal UI REPL prompt that includes portal data inspector, namespace reloading and library hotload tools. <code>test</code> path is included to support editor test runners and <code>dev</code> path for custom user namespace for custom REPL startup</p> Task Command Defined In Basic terminal UI REPL <code>clojure</code> (or <code>clj</code> if <code>rlwrap</code> binary installed) Clojure CLI Enhanced terminal UI REPL (Rebel &amp; nREPL) <code>clojure -M:repl/rebel</code> or <code>clojure -M:repl/reloaded</code> Practicalli Create project <code>clojure -T:project/new :template app :name domain/appname :args '[\"+h2\"]'</code> Practicalli Run unit tests / watch for changes <code>clojure -X:test/run</code> or <code>clojure -X:test/watch</code> Practicalli Run the project (clojure.main) <code>clojure -M -m domain.main-namespace</code> No Alias Find libraries (maven &amp; git) <code>clojure -M:search/library library-name</code> Practicalli Find library versions (maven) <code>clojure -X:deps find-versions domain/library-name</code> CLojure CLI Download dependencies <code>clojure -P</code>  (plus optional execution flags with aliases) CLojure CLI Check for new dependency versions <code>clojure -T:search/outdated</code> Practicalli Package library <code>clojure -X:build/jar</code> and <code>clojure -X:build/uberjar</code> Practicalli Deploy library locally <code>clojure -X:deps mvn-install</code> Clojure CLI Check code for unused vars <code>clojure -X:search/unused</code> Practicalli <p>tools.build is recommended for packaging projects</p> <p>Package with tools.build is the recommended approach to create jar and Uberjar packages of a Clojure project.</p>"},{"location":"clojure-cli/#execution-option-flags","title":"Execution option flags","text":"<p>The execution option flags for the <code>clojure</code> command define how to run Clojure code.  The most commonly used options are:</p> <ul> <li><code>-M</code> uses clojure.main and calls the <code>-main</code> function of the given namespace, passing positional string arguments.</li> <li><code>-X</code> uses clojure.exec to call a fully qualified function which has a map argument, passing key/value pair arguments. <code>-T</code> is the same as <code>-X</code> execpt setting the classpath to <code>.</code>, ignoring project dependencies not defined in a given alias.</li> </ul> Flag Purpose <code>-A</code> Pass alias to built-in terminal UI REPL (<code>clojure</code> or <code>clj</code>) <code>-M</code> Run Clojure with clojure.main <code>-P</code> Prepare / dry run (Build scripts, CI servers, Containers) <code>-X</code> Execute a fully qualified function, optional default arguments <code>-T</code> Run a tool independently from a project configuration <code>-J</code> Java Virtual Machine specific options (heap size, etc) <p>Examples of execution option flags</p> <p>Execution option page expands on flag usage with numerous examples</p>"},{"location":"clojure-cli/#configure-clojure-cli","title":"Configure Clojure CLI","text":"<p>A <code>deps.edn</code> file configures the Clojure CLI, using extensible data notation (EDN), the underlying syntax of Clojure itself.</p> <p>Configuration is defined using a hash-map with the following top-level keys:</p> <ul> <li><code>:deps</code> - library dependencies</li> <li><code>:paths</code> - directories to search for code and resources (Java classpath)</li> <li><code>:aliases</code> - named configuration defining extra paths, extra deps and configuration to run Clojure</li> <li><code>:mvn/repos</code> - library dependency sources, remote and local (e.g. Clojars, Maven, Artifactory, etc).</li> </ul> <p><code>:aliases</code> configuration is only included when using the alias name with the Clojure CLI, e.g. <code>:repl/rebel</code> alias in  Practicalli Clojure CLI Config adds library dependencies only used during development to run a rich terminal UI REPL.</p> <pre><code>clojure -M:repl/rebel\n</code></pre> Add a wide range of aliases by installing  Practicalli Clojure CLI Config <p> Practicalli Clojure CLI Config provides aliases for a wide range of tools for use with Clojure CLI to support Clojure software development.</p>"},{"location":"clojure-cli/#precedence-order","title":"Precedence Order","text":"<p>Clojure CLI Configuration can be used from several different sources.</p> Configuration Description Command line arguments string or edn (key value) arguments passed to the <code>clojure</code> command project <code>deps.edn</code> Project specific configuration: paths, dependencies, aliases <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> / <code>$HOME/.clojure/deps.edn</code> User level configuration for use with all projects Clojure CLI install Includes Clojure standard library, <code>src</code> path and built-in <code>:deps</code> aliases <p></p> <p>Command line arguments take preceedence over the other configurations. When running the <code>clojure</code> command the configurations are merged, with key/values being added or replaces following the precedence order.</p>"},{"location":"clojure-cli/#install-configuration","title":"Install configuration","text":"<p>Clojure CLI install has a built-in configuration:</p> <ul> <li><code>org.clojure/clojure</code> library dependency, setting the default version of Clojure for the Clojure CLI</li> <li><code>src</code> set as the default path</li> </ul> Clojure CLI Install deps.edn <p>The Clojure CLI install includes a <code>deps.edn</code> configuration, e.g. <code>/usr/local/lib/clojure/deps.edn</code> <pre><code>{\n  :paths [\"src\"]\n\n  :deps {\n    org.clojure/clojure {:mvn/version \"1.11.1\"}\n  }\n\n  :aliases {\n    :deps {:replace-paths []\n           :replace-deps {org.clojure/tools.deps.cli {:mvn/version \"0.9.10\"}}\n           :ns-default clojure.tools.deps.cli.api\n           :ns-aliases {help clojure.tools.deps.cli.help}}\n    :test {:extra-paths [\"test\"]}\n  }\n\n  :mvn/repos {\n    \"central\" {:url \"https://repo1.maven.org/maven2/\"}\n    \"clojars\" {:url \"https://repo.clojars.org/\"}\n  }\n}\n</code></pre></p> Check version of Clojure <p>Evaluate <code>*clojure-version*</code> in a REPL shows which version of the Clojure language is currently being used.</p> <p>Including <code>org.clojure/clojure</code> as a dependency the project <code>deps.edn</code> file specifies a version of the Clojure language.  The Clojure CLI version is used if no other dependency is specified.</p>"},{"location":"clojure-cli/#user-configuration","title":"User configuration","text":"<p>A Clojure CLI user configuration is available to all projects by the operating system user account.   Practicalli Clojure CLI Config is a user configuration that contains a set of well-formed aliases that add common tools for all Clojure project.</p> Clojure CLI User Configuration Location <p>Clojure CLI tools creates a configuration directory called <code>.clojure</code>, which by default is placed in the root of the operating system user account directory, e.g. <code>$HOME/.clojure</code>.</p> <p><code>XDG_CONFIG_HOME</code> may be set by your operating system and over-rides the default location, e.g. <code>$HOME/.config/.clojure</code></p> <p><code>CLJ_CONFIG</code> can be used to over-ride all other location settings</p> <p>Run <code>clojure -Sdescribe</code> in a terminal and checking the <code>:config-user</code> value to see the location of your Clojure configuration directory</p> <p>A basic example of a user configuration for Clojure CLI</p> <pre><code>{\n  :aliases {\n    :test/env {:extra-paths [\"test\"]}\n\n    :project/new\n    {:extra-deps {seancorfield/clj-new {:mvn/version \"1.0.199\"}}\n     :main-opts  [\"-m\" \"clj-new.create\"]}\n  }\n\n  :mvn/repos {\n    \"central\" {:url \"https://repo1.maven.org/maven2/\"}\n    \"clojars\" {:url \"https://repo.clojars.org/\"}\n  }\n}\n</code></pre> <p>Clojure Tools install sets Clojure version</p> <p>A default version of Clojure is set by the Clojure tools install, enabling the <code>clojure</code> command to know what version of Clojure library to use.  This version will be over-ridden by the user or project specific deps.edn configuration files if set.</p>"},{"location":"clojure-cli/#references","title":"References","text":"<p>tools.deps and cli guide clojure.main API Reference tools.deps.alpha API Reference</p>"},{"location":"clojure-cli/built-in-commands/","title":"Clojure CLI Built-in commands","text":"<p><code>clojure</code> without any other arguments will run a REPL with a basic terminal prompt.  </p> <p><code>clj</code> is a wrapper script for the <code>clojure</code> command (<code>rlwrap</code> required) to add command history to the basic REPL prompt.</p> <p><code>clojure -T:deps</code> to run one of several built-in commands to help work with Clojure CLI projects and libraries.</p> <p><code>clojure --help</code> list the available commands.</p>"},{"location":"clojure-cli/built-in-commands/#deps-alias","title":":deps alias","text":"<p>The <code>:deps</code> aliases provides tools for managing library dependencies.  </p> <p>The Clojure CLI <code>-X</code> flag is used to call these tools via <code>clojure.exec</code> and take key value pairs as arguments</p> aliases Description <code>clojure -X:deps list</code> List full transitive deps set and licenses <code>clojure -X:deps tree</code> download dependencies &amp; print dependency tree, indenting libraries that are dependencies of dependencies <code>clojure -X:deps find-versions</code> Find available versions of a given library (domain/name) <code>clojure -X:deps prep</code> Prepare all unprepped libs in the dep tree <code>clojure -X:deps mvn-pom</code> Generate or update pom.xml with deps and paths <code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'</code> install a given jar file into the local maven repository, eg. <code>~/.m2/repository</code> <code>clojure -X:deps git-resolve-tags</code> update <code>deps.edn</code> git based dependencies that used tags with the equivalent SHA commit values <p>tools.deps.alpha API Reference</p> <p>Libraries are downloaded if they are not in the local Maven cache, e.g. <code>$HOME/.m2/repository</code>, so on first run a command may take a little time.</p> Use Clojure CLI -P flag to download libraries <p><code>clojure -P</code> is the recommended way to download library dependencies as it does not run any other commands</p> <p>The <code>-P</code> flag can be used with aliases to download libraries for building and testing a Clojure project, especially useful for a cached environment like Docker.</p> <pre><code>clojure -P -M:dev/reloaded:project/build\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#list-library-dependencies","title":"List Library dependencies","text":"<p>List library depenencies of a project, including the library version and software licence for each library.</p> <p>The list includes transitive dependencies, library dependencies of the project library dependencies.</p> <p>The <code>:aliases '[:alias/name(s)]'</code> argument will also list library dependencies from a given alias, either project alias or user alias. </p> <pre><code>clojure -X:deps list\n</code></pre> Dependency list from Practicalli Service project template <pre><code> \u276f clojure -X:deps list\naero/aero 1.1.6  (MIT)\namalloy/ring-buffer 1.3.1  (EPL-1.0)\naysylu/loom 1.0.2  (EPL-1.0)\nborkdude/dynaload 0.2.2  (EPL-1.0)\nborkdude/edamame 0.0.18  (EPL-1.0)\ncom.bhauman/spell-spec 0.1.2  (EPL-1.0)\ncom.brunobonacci/mulog 0.9.0  (Apache-2.0)\ncom.brunobonacci/mulog-adv-console 0.9.0  (Apache-2.0)\ncom.brunobonacci/mulog-json 0.9.0  (Apache-2.0)\ncom.cnuernber/charred 1.010\ncom.cognitect/transit-clj 1.0.324  (Apache-2.0)\ncom.cognitect/transit-java 1.0.343  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-annotations 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-core 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-databind 2.12.1  (Apache-2.0)\ncom.fasterxml.jackson.datatype/jackson-datatype-jsr310 2.12.0  (Apache-2.0)\ncom.google.javascript/closure-compiler v20151015  (Apache-2.0)\ncom.googlecode.json-simple/json-simple 1.1.1  (Apache-2.0)\ncommons-codec/commons-codec 1.15  (Apache-2.0)\ncommons-fileupload/commons-fileupload 1.4  (Apache-2.0)\ncommons-io/commons-io 2.6  (Apache-2.0)\ncrypto-equality/crypto-equality 1.0.0  (EPL-1.0)\ncrypto-random/crypto-random 1.2.0  (EPL-1.0)\nexpound/expound 0.9.0  (EPL-1.0)\nfipp/fipp 0.6.25  (EPL-1.0)\nhttp-kit/http-kit 2.6.0  (Apache-2.0)\njavax.xml.bind/jaxb-api 2.3.0  (CDDL 1.1)\nlambdaisland/deep-diff 0.0-47  (EPL-1.0)\nmeta-merge/meta-merge 1.0.0  (EPL-1.0)\nmetosin/jsonista 0.3.1  (EPL-1.0)\nmetosin/malli 0.7.5  (EPL-2.0)\nmetosin/muuntaja 0.6.8  (EPL-1.0)\nmetosin/reitit 0.5.13  (EPL-1.0)\nmetosin/reitit-core 0.5.18  (EPL-1.0)\nmetosin/reitit-dev 0.5.18  (EPL-1.0)\nmetosin/reitit-frontend 0.5.13  (EPL-1.0)\nmetosin/reitit-http 0.5.13  (EPL-1.0)\nmetosin/reitit-interceptors 0.5.13  (EPL-1.0)\nmetosin/reitit-malli 0.5.13  (EPL-1.0)\nmetosin/reitit-middleware 0.5.13  (EPL-1.0)\nmetosin/reitit-ring 0.5.13  (EPL-1.0)\nmetosin/reitit-schema 0.5.13  (EPL-1.0)\nmetosin/reitit-sieppari 0.5.13  (EPL-1.0)\nmetosin/reitit-spec 0.5.13  (EPL-1.0)\nmetosin/reitit-swagger 0.5.13  (EPL-1.0)\nmetosin/reitit-swagger-ui 0.5.13  (EPL-1.0)\nmetosin/ring-swagger-ui 3.36.0  (EPL-1.0)\nmetosin/schema-tools 0.12.3  (EPL-1.0)\nmetosin/sieppari 0.0.0-alpha13  (EPL-1.0)\nmetosin/spec-tools 0.10.5  (EPL-1.0)\nmvxcvi/arrangement 2.0.0  (Public Domain)\nmvxcvi/puget 1.1.2  (Public Domain)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/clojurescript 1.7.170  (EPL-1.0)\norg.clojure/core.rrb-vector 0.0.14  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 0.2.6  (EPL-1.0)\norg.clojure/data.priority-map 0.0.5  (EPL-1.0)\norg.clojure/google-closure-library 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/google-closure-library-third-party 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/java.classpath 1.0.0  (EPL-1.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/test.check 1.1.1  (EPL-1.0)\norg.clojure/tools.namespace 1.3.0  (EPL-1.0)\norg.clojure/tools.reader 1.3.6  (EPL-1.0)\norg.javassist/javassist 3.18.1-GA  (MPL 1.1)\norg.mozilla/rhino 1.7R5  (Mozilla Public License, Version 2.0)\norg.msgpack/msgpack 0.6.12  (Apache-2.0)\nparty.donut/system 0.0.202 \nprismatic/schema 1.1.12  (EPL-1.0)\nring/ring-codec 1.1.3  (MIT)\nring/ring-core 1.9.1  (MIT)\ntailrecursion/cljs-priority-map 1.2.1  (EPL-1.0)\ntech.droit/clj-diff 1.0.1  (EPL-1.0)\n</code></pre> <p>Use the <code>:aliases '[:alias/name(s)]'</code> option to also include the dependencies from a project or user alias.  Showing the dependencies from an aliase can useful to identify conflicting dependencies when using an alias (unlikely but it could happen).</p> <pre><code>clojure -X:deps list :aliases '[:dev/reloaded]'\n</code></pre> Dependency list from project and Practicalli :dev/reloaded alias <pre><code>\u276f clojure -X:deps list :aliases '[:dev/reloaded]'\naero/aero 1.1.6  (MIT)\namalloy/ring-buffer 1.3.1  (EPL-1.0)\nclj-commons/clj-yaml 1.0.27  (EPL-1.0)\ncom.brunobonacci/mulog 0.9.0  (Apache-2.0)\ncom.cognitect/transit-clj 1.0.333  (Apache-2.0)\ncom.cognitect/transit-cljs 0.8.280  (Apache-2.0)\ncom.cognitect/transit-java 1.0.371  (Apache-2.0)\ncom.cognitect/transit-js 0.8.874  (Apache-2.0)\ncom.fasterxml.jackson.core/jackson-core 2.14.2  (Apache-2.0)\ncom.google.code.gson/gson 2.10.1  (Apache-2.0)\ncom.googlecode.json-simple/json-simple 1.1.1  (Apache-2.0)\ncom.nextjournal/beholder 1.0.2 \ncriterium/criterium 0.4.6  (EPL-1.0)\ndjblue/portal 0.49.0  (MIT)\nexpound/expound 0.9.0  (EPL-1.0)\nfipp/fipp 0.6.26  (EPL-1.0)\nhawk/hawk 0.2.11  (EPL-1.0)\nhttp-kit/http-kit 2.7.0  (Apache-2.0)\nio.methvin/directory-watcher 0.17.3  (Apache-2.0)\njavax.activation/javax.activation-api 1.2.0  (CDDL/GPLv2+CE)\njavax.xml.bind/jaxb-api 2.4.0-b180830.0359  (CDDL 1.1)\nlambdaisland/clj-diff 1.4.78  (EPL-1.0)\nlambdaisland/deep-diff2 2.10.211  (EPL-1.0)\nlambdaisland/kaocha 1.87.1366  (EPL-1.0)\nlambdaisland/tools.namespace 0.3.256  (EPL-1.0)\nmeta-merge/meta-merge 1.0.0  (EPL-1.0)\nmvxcvi/arrangement 2.1.0  (Public Domain)\nnet.incongru.watchservice/barbary-watchservice 1.0  (GPLv2 + Classpath Exception)\nnet.java.dev.jna/jna 5.12.1  (LGPL-2.1-or-later)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/core.rrb-vector 0.1.2  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 2.4.0  (EPL-1.0)\norg.clojure/java.classpath 1.0.0  (EPL-1.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/test.check 1.1.1  (EPL-1.0)\norg.clojure/tools.cli 1.0.219  (EPL-1.0)\norg.clojure/tools.namespace 1.4.4  (EPL-1.0)\norg.clojure/tools.reader 1.3.6  (EPL-1.0)\norg.clojure/tools.trace 0.7.11  (EPL-1.0)\norg.flatland/ordered 1.15.11  (EPL-1.0)\norg.javassist/javassist 3.18.1-GA  (MPL 1.1)\norg.msgpack/msgpack 0.6.12  (Apache-2.0)\norg.slf4j/slf4j-api 2.0.9  (MIT)\norg.slf4j/slf4j-nop 2.0.9  (MIT)\norg.tcrawley/dynapath 1.1.0  (EPL-1.0)\norg.yaml/snakeyaml 2.1  (Apache-2.0)\nprogrock/progrock 0.1.2  (EPL-1.0)\nslingshot/slingshot 0.12.2  (EPL-1.0)\n</code></pre> <p>The <code>:aliases</code> option can be used to inspect the dependencies of a user alias, listing only dependencies from the specified aliases when run outside of a Clojure project.</p> Dependency list from Practicalli :repl/rebel alias only <pre><code>\u276f clojure -X:deps list :aliases '[:repl/rebel]'\ncider/cider-nrepl 0.42.1  (EPL-1.0)\ncider/orchard 0.18.0  (EPL-1.0)\ncljfmt/cljfmt 0.5.7  (EPL-1.0)\ncom.bhauman/rebel-readline 0.1.4  (EPL-1.0)\ncom.google.javascript/closure-compiler v20151216  (Apache-2.0)\ncompliment/compliment 0.3.6  (EPL-1.0)\nmx.cider/logjam 0.1.1  (EPL-1.0)\nnrepl/nrepl 1.1.0  (EPL-1.0)\norg.clojure/clojure 1.11.1  (EPL-1.0)\norg.clojure/clojurescript 1.7.228  (EPL-1.0)\norg.clojure/core.specs.alpha 0.2.62  (EPL-1.0)\norg.clojure/data.json 0.2.6  (EPL-1.0)\norg.clojure/google-closure-library 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/google-closure-library-third-party 0.0-20151016-61277aea  (Apache-2.0)\norg.clojure/spec.alpha 0.3.218  (EPL-1.0)\norg.clojure/tools.reader 1.0.0-alpha4  (EPL-1.0)\norg.fusesource.jansi/jansi 1.16  (Apache-2.0)\norg.jline/jline-reader 3.5.1  (The BSD License)\norg.jline/jline-terminal 3.5.1  (The BSD License)\norg.jline/jline-terminal-jansi 3.5.1  (The BSD License)\norg.mozilla/rhino 1.7R5  (Mozilla Public License, Version 2.0)\nrewrite-clj/rewrite-clj 0.5.2  (MIT)\nrewrite-cljs/rewrite-cljs 0.4.3  (MIT)\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#dependency-tree","title":"Dependency tree","text":"<p>Show a tree hieracthy of project library dependencies, including the library name and version used.</p> <p>The tree includes transitive dependencies, library dependencies of the project library dependencies.</p> <p>The <code>:aliases '[:alias/name(s)]'</code> argument will also list library dependencies from a given alias, either project alias or user alias. </p> <pre><code>clojure -X:deps tree\n</code></pre> Dependency list from Practicalli Service project template <pre><code>\u276f clojure -X:deps tree\norg.clojure/clojure 1.11.1\n  . org.clojure/spec.alpha 0.3.218\n  . org.clojure/core.specs.alpha 0.2.62\nhttp-kit/http-kit 2.6.0\nmetosin/reitit 0.5.13\n  X metosin/reitit-core 0.5.13 :superseded\n    X meta-merge/meta-merge 1.0.0 :parent-omitted\n  X metosin/reitit-dev 0.5.13 :use-top\n  . metosin/reitit-spec 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/spec-tools 0.10.5\n      X org.clojure/spec.alpha 0.2.187 :older-version\n  . metosin/reitit-malli 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    X metosin/malli 0.3.0 :older-version\n  . metosin/reitit-schema 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/schema-tools 0.12.3\n      . prismatic/schema 1.1.12\n  . metosin/reitit-ring 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . ring/ring-core 1.9.1\n      . ring/ring-codec 1.1.3\n        . commons-codec/commons-codec 1.15\n      . commons-io/commons-io 2.6\n      . commons-fileupload/commons-fileupload 1.4\n        X commons-io/commons-io 2.2 :older-version\n      . crypto-random/crypto-random 1.2.0\n        X commons-codec/commons-codec 1.6 :older-version\n      . crypto-equality/crypto-equality 1.0.0\n  . metosin/reitit-middleware 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . lambdaisland/deep-diff 0.0-47\n      . mvxcvi/puget 1.1.2\n        X mvxcvi/arrangement 1.2.0 :older-version\n        X fipp/fipp 0.6.17 :older-version\n      X fipp/fipp 0.6.17 :older-version\n      . org.clojure/core.rrb-vector 0.0.14\n      . tech.droit/clj-diff 1.0.1\n      X mvxcvi/arrangement 1.2.0 :older-version\n    . metosin/muuntaja 0.6.8\n      . metosin/jsonista 0.3.1\n      . com.cognitect/transit-clj 1.0.324\n        . com.cognitect/transit-java 1.0.343\n          X com.fasterxml.jackson.core/jackson-core 2.8.7 :older-version\n          . org.msgpack/msgpack 0.6.12\n            . com.googlecode.json-simple/json-simple 1.1.1\n            . org.javassist/javassist 3.18.1-GA\n          X commons-codec/commons-codec 1.10 :older-version\n          . javax.xml.bind/jaxb-api 2.3.0\n    . metosin/spec-tools 0.10.5\n  . metosin/reitit-http 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/reitit-ring 0.5.13\n  . metosin/reitit-interceptors 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . lambdaisland/deep-diff 0.0-47\n    . metosin/muuntaja 0.6.8\n  . metosin/reitit-swagger 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n  . metosin/reitit-swagger-ui 0.5.13\n    . metosin/reitit-ring 0.5.13\n    . metosin/jsonista 0.3.1\n      X com.fasterxml.jackson.core/jackson-core 2.12.0 :older-version\n      X com.fasterxml.jackson.core/jackson-databind 2.12.0 :older-version\n      . com.fasterxml.jackson.datatype/jackson-datatype-jsr310 2.12.0\n        X com.fasterxml.jackson.core/jackson-annotations 2.12.0 :older-version\n        X com.fasterxml.jackson.core/jackson-core 2.12.0 :older-version\n        X com.fasterxml.jackson.core/jackson-databind 2.12.0 :older-version\n    . metosin/ring-swagger-ui 3.36.0\n  . metosin/reitit-frontend 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n  . metosin/reitit-sieppari 0.5.13\n    X metosin/reitit-core 0.5.13 :older-version\n    . metosin/sieppari 0.0.0-alpha13\n  . com.fasterxml.jackson.core/jackson-core 2.12.1\n  . com.fasterxml.jackson.core/jackson-databind 2.12.1\n    . com.fasterxml.jackson.core/jackson-annotations 2.12.1\n    . com.fasterxml.jackson.core/jackson-core 2.12.1\nmetosin/reitit-dev 0.5.18\n  . metosin/reitit-core 0.5.18 :newer-version\n    . meta-merge/meta-merge 1.0.0\n  . com.bhauman/spell-spec 0.1.2\n  . expound/expound 0.9.0\n  . fipp/fipp 0.6.25\ncom.brunobonacci/mulog 0.9.0\n  . amalloy/ring-buffer 1.3.1\ncom.brunobonacci/mulog-adv-console 0.9.0\n  X com.brunobonacci/mulog 0.9.0 :use-top\n  . com.brunobonacci/mulog-json 0.9.0\n    X com.brunobonacci/mulog 0.9.0 :use-top\n    . com.cnuernber/charred 1.010\naero/aero 1.1.6\nparty.donut/system 0.0.202\n  . aysylu/loom 1.0.2\n    . org.clojure/data.priority-map 0.0.5\n    . tailrecursion/cljs-priority-map 1.2.1\n      . org.clojure/clojurescript 1.7.170\n        . com.google.javascript/closure-compiler v20151015\n        . org.clojure/google-closure-library 0.0-20151016-61277aea\n          . org.clojure/google-closure-library-third-party 0.0-20151016-61277aea\n        . org.clojure/data.json 0.2.6\n        . org.mozilla/rhino 1.7R5\n        X org.clojure/tools.reader 0.10.0-alpha3 :older-version\n  . org.clojure/tools.namespace 1.3.0\n    . org.clojure/java.classpath 1.0.0\n    . org.clojure/tools.reader 1.3.6\n  . metosin/malli 0.7.5\n    . borkdude/dynaload 0.2.2\n    . borkdude/edamame 0.0.18\n      X org.clojure/tools.reader 1.3.4 :older-version\n    . org.clojure/test.check 1.1.1\n    X fipp/fipp 0.6.24 :older-version\n    . mvxcvi/arrangement 2.0.0\n</code></pre> <p>Use the <code>:aliases</code> option with the Clojure CLI in the root of a project to show library dependencies for the project and the <code>:dev/reloaded</code> alias which could be useful if there are library conflicts when using an alias (unlikely but it could happen).</p> <pre><code>clojure -X:deps tree :aliases '[:dev/reloaded]'\n</code></pre> <p>The <code>:aliases</code> option can be used to inspect the dependencies of a user alias, listing only dependencies from the specified aliases when run outside of a Clojure project.</p> Dependency list from Practicalli :repl/rebel alias only <pre><code> \u276f clojure -X:deps tree :aliases '[:repl/rebel]'\norg.clojure/clojure 1.11.1\n  . org.clojure/spec.alpha 0.3.218\n  . org.clojure/core.specs.alpha 0.2.62\nnrepl/nrepl 1.1.0\ncider/cider-nrepl 0.42.1\n  X nrepl/nrepl 1.0.0 :use-top\n  . cider/orchard 0.18.0\n  . mx.cider/logjam 0.1.1\ncom.bhauman/rebel-readline 0.1.4\n  . org.jline/jline-reader 3.5.1\n    . org.jline/jline-terminal 3.5.1\n  . org.jline/jline-terminal 3.5.1\n  . org.jline/jline-terminal-jansi 3.5.1\n    . org.fusesource.jansi/jansi 1.16\n    . org.jline/jline-terminal 3.5.1\n  . cljfmt/cljfmt 0.5.7\n    . org.clojure/tools.reader 1.0.0-alpha4\n    . rewrite-clj/rewrite-clj 0.5.2\n      X org.clojure/tools.reader 0.10.0 :older-version\n    . rewrite-cljs/rewrite-cljs 0.4.3\n      . org.clojure/clojurescript 1.7.228\n        . com.google.javascript/closure-compiler v20151216\n        . org.clojure/google-closure-library 0.0-20151016-61277aea\n          . org.clojure/google-closure-library-third-party 0.0-20151016-61277aea\n        . org.clojure/data.json 0.2.6\n        . org.mozilla/rhino 1.7R5\n        X org.clojure/tools.reader 1.0.0-alpha1 :older-version\n      X org.clojure/tools.reader 1.0.0-alpha3 :older-version\n  . compliment/compliment 0.3.6\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#local-library-install","title":"Local library install","text":"<p>Add a jar file for a library to the local Maven repository, e.g. <code>~/.m2/repository</code>, making that library accessible to all other local projects.</p> <pre><code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'`\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#find-library-versions","title":"Find Library Versions","text":"<p>Find the available versions of a given library in the form domain/library-name (domain is typically the company name or Git Service user or organisation name).</p> <pre><code>clojure -X:deps find-versions :lib clojure.java-time/clojure.java-time\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#prepare-source-dependencies","title":"Prepare Source dependencies","text":"<p>Some dependencies will require a preparation step before they can be used on the classpath.</p> <p>Projects that require preparation would have a configuration of the form:</p> <p>Example</p> <pre><code>{:paths [\"src\" \"target/classes\"]\n :deps/prep-lib {:alias :build\n                 :fn compile\n                 :ensure \"target/classes\"}}\n</code></pre> <p>Including the top-level key <code>:deps/prep-lib</code> tells the tools.deps classpath construction that something extra is needed to prepare this lib and that can be performed by invoking the compile function in the :build alias. Once the prepare step has been done, it should create the path \"target/classes\" and that can be checked for completion.</p> <p>Add a library dependency as with any other library (git or local/root):</p> <p>Example</p> <pre><code>{:deps {practicalli/library-name {:local/root \"../needs-prep\"}\n        practicalli/library-name {:git/sha \"../needs-prep\"}}}\n</code></pre> <p><code>:deps prep</code> will built the library of any dependency that requires it</p> <pre><code>clojure -X:deps prep\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#pom-file","title":"POM file","text":"<p>Generate or update pom.xml with deps and paths</p> <pre><code>clojure -X:deps mvn-pom\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#resolve-git-tags","title":"Resolve Git tags","text":"<p><code>-X:deps git-resolve-tags</code> updates git based dependencies in the project <code>deps.edn</code> file which use :git/tags key to the equivalent SHA commit values in the <code>:git/sha</code> key</p> <pre><code>clojure -X:deps git-resolve-tags\n</code></pre>"},{"location":"clojure-cli/built-in-commands/#references","title":"References","text":"<p>tools.deps and cli guide clojure.main guide clojure.main API Reference tools.deps.alpha API Reference</p>"},{"location":"clojure-cli/clojure-style/","title":"Clojure Style","text":"<p>Code is easier to read and work with when it is consistent format that follows common rules.</p> <p>Clojure community style guide provides a common style for Clojure code.  While most style recommendations are widely used, others are more contentious.  Ultimately the development team for the project should define a workable set of style rules that makes them productions, ideally using much of those rules from the style guide.</p> <p>A consistent format between editors also minimises version control changes not related to code design.  The following format tools for clojure can all be configured to be consistent with each other (although zprint defaults will require more customisation):</p> <ul> <li>cljfmt - library, also included in Clojure LSP</li> <li>cljstyle - binary and library (re-write of cljfmt)</li> <li>zprint - binary &amp; library</li> </ul> Tooling that uses the Clojure Style Guide <p>Emacs <code>clojure-mode</code> and Clojure LSP (via cljfmt) format code following the most common Clojure style guide rules, although cljfmt rules are quite strick so Practicalli disables many of them.</p> <p>cljstyle default configuration follows the majority of styles and has the same defaults as cljfmt.  Practicalli Clojure CLI Config tweaks a few rules to make code more readable and allow for repl design experiments.</p>"},{"location":"clojure-cli/clojure-style/#cljstyle","title":"cljstyle","text":"<p>Cljstyle is a rewrite of cljfmt, designed to be easier to configure. The default rules implement many of the style rules from the Clojure community style guide and is compatible with cljfmt.</p> <p>Call with the <code>check</code> option to report formatting issues, providing a coloured diff view of the format changes</p> <p> </p> <p>Call with <code>fix</code> option to automatically update all Clojure files with fixes, indicating which files have changed.</p> <p>Cljstyle will examine all files in the current directory and any sub-directories.</p> <p><code>.cljstyle</code> configuration file in the root of the project can override the default customisation, including indentation rules.</p> <p>cljstyle config used by Practicalli</p> <p>Clojure App template repository contains the <code>.cljstyle</code> configuration file used for all Practicalli projects</p> Binary Practicalli Clojure CLI ConfigMakefile <p>Install the latest binary release from the cljstyle GitHub repository onto the operating system path, e.g. <code>$HOME/.local/bin</code></p> <pre><code>cljstyle check\n</code></pre> <p><code>fix</code> option automatically updates all source code files that have format issues.</p> <pre><code>cljstyle fix\n</code></pre> <p>cljstyle can be used as a library without installing the cljstyle binary.   Practicalli Clojure CLI Config defines the <code>:format/cljstyle</code> alias which should be passed wither the <code>check</code> or <code>format</code> option</p> <p>Check all the Clojure files (.clj .cljc .edn .cljs) in the current project <pre><code>clojure -M:format/cljstyle\n</code></pre></p> <pre><code>clojure -M:format/cljstyle!\n</code></pre> <p>Clojure Alias for cljstyle</p> <pre><code>:format/cljstyle\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"check\"]}\n\n:format/cljstyle!\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"fix\"]}\n</code></pre> <p>Use a Makefile to run common commands such as checking style, running tests, building uberjars, etc.</p> <p>Practicalli Clojure App template repository contains an example Makefile that contains common tasks for Clojure development</p> <p>This example calls the cljstyle binary, but could be changed to call the <code>clojure -M:format/cljstyle check</code> and <code>clojure -M:format/cljstyle fix</code> aliases instead.</p> <pre><code># ------- Code Quality --------------- #\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n# ------------------------------------ #\n</code></pre> <p>Stage changes before automatically fixing format</p> <p>Practicalli suggests staging (or committing) changes before running <code>cljstyle fix</code> to easily undo undesired changes or simply confirm what changes have been made</p>"},{"location":"clojure-cli/clojure-style/#recommended-configuration","title":"Recommended configuration","text":"<p>Practicalli updated the default cljstyle configuration with the following changes</p> <p>Configure list indent to one character</p> .cljstyle<pre><code>  :indentation\n  {:enabled? true,\n   :list-indent 1,\n\n  }\n</code></pre> <p>Do not warn about duplicate var names (def, defn names) - excluded to stop warning about REPL experiments and design journal rich comments that contain alternative designs.</p> .cljstyle<pre><code>  :vars\n  {:enabled? false}\n</code></pre>"},{"location":"clojure-cli/clojure-style/#cljfmt","title":"cljfmt","text":"<p>cljfmt is not available as a separate binary, although it a fixed part of the Clojure LSP server implementation.</p> <p>whist typing Clojure code, Clojure LSP will format using cljfmt rules</p> <p>Define a cljfmt configuration via Clojure LSP to define rules and indentation settings for all projects.</p> .config/clojure-lsp/config.edn<pre><code> :cljfmt-config-path \"cljfmt.edn\"\n</code></pre> <p>Or specify cljfmt configuration within the Clojure LSP configuration file</p> .config/clojure-lsp/config.edn<pre><code> :cljfmt {}\n</code></pre> Practicalli Clojure LSP config - LSP and cljfmt <p>Practicalli Clojure LSP config provides an example config.edn configuration file for Clojure LSP that uses a cljfmt.edn configuration file for a minimum set of Clojure format rules</p> <p>The default cljfmt rules feel overly strict and Practicalli configuration disables the more draconian rules to make code far more readable</p>"},{"location":"clojure-cli/clojure-style/#zprint","title":"zprint","text":"<p>zprint is a highly configurable format tool for both Clojure code and Clojure/EDN structures, available as a library and command line tool</p> <p>zprint has advanced features over cljstyle and cljfmt, although may require some additional configuration work especially to format consistently with these tools.</p> <p>zprint available styles</p> No built-in diff option <p>zprint requires an external diff tool to see the format changes made, as zprint only reports on the files changed and not the content of those files that has changed.</p> <p>zprint can write changes to a new file and a file comparison made.  Or files can be staged / committed in a local Git repository before running zprint and a Git client used to see the diff.</p> <p>Once the desirable styles and configuration are established there is less need for an external diff tool, although its always useful to have a quick way to check what format tools are doing.</p> Binary Practicalli Clojure CLI ConfigNode.js <p>Download zprint for Linux or MacOSX using the latest binary released on the GitHub repository</p> <p>Move the binary to the executable path for the operating system, updating the name to <code>zprint</code> (or use a symbolic link)</p> <p><pre><code>mv ~/Downloads/zprintl-1.2.5 ~/.local/bin/zprint\n</code></pre> Make the binary executable <pre><code>chmod a+x ~/.local/bin/zprint\n</code></pre> Ensure the zprint binary is working and examine the default configuration for zprint, including all default values and highlighting where non-default values are set <pre><code>zprint --explain-all\n</code></pre> Using zprint to check the Clojure files in the current directory and list which files require formatting <pre><code>zprint --formatted-check *.clj\n</code></pre></p> <p>A more detailed zprint report checking all the Clojure files a project, including files in the route directory and all sub-directories (i.e. <code>**/*.cjl</code> pattern) <pre><code>zprint --list-formatted-summary-check **/*.clj **/*.edn\n</code></pre> Or using short form flags <pre><code>zprint -lfsc **/*.clj **/*.edn\n</code></pre></p> <p>Update formatting for all the files in a projects, showing details of the files processed and changed <pre><code>zprint -lfsw **/*.clj *.edn *.clj\n</code></pre></p> <p>zprint can be used as a library without installing the binary.   Practicalli Clojure CLI Config defines the <code>:format/zprint</code> alias which checks the format of a file and reports which files required</p> <pre><code>clojure -M:format/zprint deps.edn\n</code></pre> <pre><code>clojure -M:format/zprint filename\n</code></pre> Clojure Alias for zprint <p>Add <code>:format/zprint</code> alias to check format and <code>:format/zprint!</code> to write format changes to a given file or filename pattern User or project deps.edn file<pre><code>:format/zprint\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-check\"]}\n\n:format/zprint!\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-write\"]}\n</code></pre> Use the alise</p> <p>zprint is available as an NPM package <pre><code>sudo --install --global zprint-clj\n</code></pre> Run zprint-clj over all Clojure files <pre><code>zprint-clj **/*.{clj,cljs,cljc,edn}\n</code></pre></p>"},{"location":"clojure-cli/clojure-style/#configure-zprint","title":"Configure zprint","text":"<p>It is assumed that the majority of format needs are met by one of the following style rule sets</p> <ul> <li><code>{:style :indent-only}</code> only formats indentation, less likely to change the general style of code</li> <li><code>{:style :community}</code> a quite strict adhearence to the Clojure Community Guide (which Practicalli finds a little to strict)</li> </ul> <p>Unless the code is really messy (e.g. not written in a clojure aware editor with live linting) then <code>{:style :indent-only}</code> is a simple starting point.</p> <p>If the team have adopted most if not all community styles, then <code>{:style :community}</code> may be a more appropriate start point.  Use --explain-all flag with the zprint command to see all the rules that are applied with a partiular style and modify as appropriate</p> <p><code>$HOME/.zprintrc</code> is used for the configuration applied to all files, although this can be overridden in each project (or even as zprint comments in particular files)</p> <p>zprint - GitHub repo zprint - clojars zprint - cljdoc</p>"},{"location":"clojure-cli/defining-aliases/","title":"Defining aliases","text":"<p>Aliases extend the built-in functionality of Clojure CLI via community libraries and tools, either in a project specific or a user <code>deps.edn</code> configuration file.</p> <p>Aliases are explicitly added to the <code>clojure</code> command, e.g. <code>clojure -M:repl/rebel</code> to start a repl with rebel rich terminal UI.</p> <p>Aliases are optional configuration that supports the development workflow.</p> <p>Aliases can be used to :</p> <ul> <li>add libraries and directories to the class path</li> <li>configure how to run community tools and provide default options</li> </ul> Understanding Clojure CLI Execution Options <p>Understand the execution options (exec-opts) on the command line options ensures an effective use of Clojure CLI tools.</p>"},{"location":"clojure-cli/defining-aliases/#configuration-file","title":"Configuration file","text":"<p><code>deps.edn</code> is an EDN configuration file containing a single hash-map with several top-level keywords. All keywords are optional.</p> <ul> <li><code>:paths</code> - directories included by default as a vector of directory names, e.g. <code>[\"src\" \"resources\"]</code></li> <li><code>:deps</code> - library dependencies included by default as a map  (practicalli/banking-on-clojure example)</li> <li><code>:mvn/repos</code> - a map of repositories to download Maven dependencies, Maven Central and Clojars included by default</li> <li><code>:mvn/local-repo</code> to specify an alternative location for the Maven cache</li> <li><code>:aliases</code> - a map of optional libraries and tools, the key being the alias name and its value the configuration</li> </ul> <p>The installation of Clojure CLI contains a configuration</p> <ul> <li>adds <code>src</code> and <code>org.clojure/clojure</code> library</li> <li>Maven Central &amp; Clojars.org repository sources.</li> </ul> <p>Configuration available to all projects (or stand-alone tools) is defined in a user <code>deps.edn</code> configuration in either <code>$XDG_CONFIG_HOME/clojure</code> or <code>$HOME/.clojure</code>.</p> <p>Project specific configuration is defined in a <code>deps.edn</code> file in the root of the Clojure project.</p> User configuration locations <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, then the user configuration is <code>$XDG_CONFIG_HOME/clojure/deps.edn</code></p> <p>Otherwide the user configuration is <code>$HOME/.clojure/deps.edn</code>.</p> <p>The <code>CLJ_CONFIG</code> environment variable will be used if set.</p>"},{"location":"clojure-cli/defining-aliases/#alias-keys","title":"Alias keys","text":"<p>An alias name is a keyword in Clojure, e.g. <code>:test/env</code>, so the <code>:</code> is an intrinsic part of the alias name.</p> <p>Keys used to define an alias are:</p> <ul> <li><code>:extra-paths</code> - a vector of directory names added to the project class path, e.g. <code>[\"env/dev\" \"env/test\"]</code></li> <li><code>:extra-deps</code> - a map of additional library dependencies, as a Maven library, Git repository or local directory</li> <li><code>{domain/library-name {:mvn/version \"1.2.33\"}}</code> maven library</li> <li><code>{domain/name {:git/url \"https://github.com/account-name/repository-name\" :git/sha 'ab3de67'}}</code></li> <li><code>{io.github.account/repository-name {:git/tag \"2023-01-10\" :git/sha 'ab3de67'}}</code></li> <li><code>{}</code></li> <li><code>:main-opts</code> - a vector of command line options passed to <code>clojure.main</code></li> <li><code>:exec-fn</code> - the fully qualified name of a function to be run by <code>clojure.exec</code></li> <li><code>:exec-args</code> - default arguments passed to the function, over-ridden by matching argument keys specified on the command line</li> </ul> <p>Keys used when defining an alias for a standalone tool which exclude the paths and dependencies defined in top-level keys.</p> <ul> <li><code>:replace-paths</code> - use only the paths specified as the class path</li> <li><code>:replace-deps</code> - use only the libraries specified, defined as a Maven library or Git repository</li> </ul> alias :paths and :deps short-cuts <p>Using <code>:paths</code> and <code>:deps</code> keys in an alias are short-cuts for their respective <code>replace-paths</code> and <code>:replace-deps</code> keywords</p> <p>Using <code>:paths</code> and <code>:deps</code> in an alias can be very confusing and Practialli recommends using the explicit names for greater clarity</p> Clojure CLI -T option <p><code>-T</code> execution option will exclude the top-level <code>:paths</code> and <code>:deps</code> keys</p> <p><code>-T</code> sets \".\" as the path, adding only paths and libraries defined in aliases used with the execution flag</p>"},{"location":"clojure-cli/defining-aliases/#clojuremain-alias","title":"clojure.main alias","text":"<p><code>:main-opts</code> specifies the options passed to a clojure.main alias, using the <code>clojure -M</code> execution option flag.</p> <p>The value is a vector containing individual string values that represent each option, i.e. option flag and value.</p> <p><code>-m</code> is used to define the fully qualified namespace in which <code>clojure.main</code> should look for the <code>-main</code> function.</p> <p>The <code>:main-opts</code> vector defines arguments that are passed to the <code>-main</code> function, the same kind of arguments that would be passed via the command line.</p> <p>The <code>\"--middleware\"</code> argument adds cider-nrepl middleware to the nREPL server, allowing Cider and other editors complete control over the REPL.  The syntax uses values wrapped in a vector.</p> <p>The <code>\"-interactive\"</code> argument runs an interactive REPL prompt. A headless process is run without this option.</p> <pre><code>  :repl/cider\n  {:extra-deps {nrepl/nrepl                   {:mvn/version \"0.9.0\"}\n                cider/cider-nrepl             {:mvn/version \"0.27.4\"}}\n   :main-opts  [\"-m\" \"nrepl.cmdline\"\n                \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n                \"-interactive\"]}\n</code></pre> <p>This alias is called using the command <code>clojure -M:repl/cider</code></p>"},{"location":"clojure-cli/defining-aliases/#clojureexec-alias","title":"clojure.exec alias","text":"<p><code>:exec-fn</code> specifies the fully qualified name of the function, using the <code>clojure -X</code> execution option flag .</p> <p><code>:exec-args</code> specifies a hash-map of default key/value pairs passed to the <code>:exec-fn</code> function.  The defaults can be overridden on the command line with respective key/value pairs.</p> <p>Arguments can be nested within the <code>:exec-args</code> map, especially useful on projects with several component configurations (server, database, logging) and managed by a component system (i.e Integrant)</p> <pre><code>{:aliases\n {:project/run\n  {:exec-fn practicalli.service/start\n   :exec-args {:http/server {:port 8080\n                             :join? fale}\n               :log/mulog :elastic-search}}}}\n</code></pre> <p>To run with the default arguments:</p> <pre><code>clojure -X:project/run\n</code></pre> <p>Over-ride the default arguments by passing them on the command line</p> <pre><code>clojure -X:project/run '[:http/server :port]' 8888 :log/mulog :console :profile :dev\n</code></pre> <p>In this command the vector defines the path to the <code>:port</code> key and over-rides the default value. :log/mulog is a top-level key which changes the log publisher type.  <code>:profile</code> is another top-level key that sets the environment to <code>:dev</code> (e.g. to configure Integrant / Aero).</p> <p>Arguments in a nested map within the alias can be traversed (as with <code>get-in</code> and <code>update-in</code> functions) to override the default values in the alias.  So to set a different port value :</p> <p>Argument keys should either be a top-level key or a vector of keys to refer to a key in a nested hash-map of arguments.</p> <p>An alias can contain configuration to run both <code>clojure.main</code> and <code>clojure.exec</code> (useful if steadily migrating users from -M to -X approach without breaking the user experience)</p>"},{"location":"clojure-cli/defining-aliases/#examples","title":"Examples","text":"Practicalli Clojure CLI Config provides a wide range of aliases <p> Practicalli Clojure CLI Config is a configuration designed to work across all Clojure projects, containing unique and meaningful alias names for ease of understanding.</p>"},{"location":"clojure-cli/defining-aliases/#simple-project","title":"Simple Project","text":"<p>A new Clojure project can be made by creating a <code>deps.edn</code> file and respective <code>src</code> &amp; <code>test</code> directory trees.</p> <p>A project <code>deps.edn</code> file typically contains <code>:path</code>, <code>:deps</code> and <code>:aliases</code> sections, although <code>deps.edn</code> could start with a simple <code>{}</code> empty hash-map.</p> <pre><code>{:paths [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}}\n\n :aliases\n {:test/env {:extra-paths [\"test\"]}}}\n</code></pre> <p>The <code>test</code> path and associated libraries are added as an alias as they are not required when packaging or running a Clojure application.  <code>:path</code> and <code>:deps</code> keys are always included by default, <code>:aliases</code> are optional and only included when specified with the <code>clojure</code> command, e.g. <code>clojure -M:test/env</code></p>"},{"location":"clojure-cli/defining-aliases/#clojuremain-tool","title":"clojure.main tool","text":"<p>The Cognitect Lab test runner included the <code>test</code> directory in the class path, so test code will be included when run with this alias.</p> <p>The test runner dependency is pulled from a specific commit shared on GitHub (defined as a Git SHA).</p> <p>The main namespace is set to that library and the <code>-main</code> function is called when using this alias.</p> <pre><code>{:aliases\n\n  :test/cognitect\n  {:extra-paths [\"test\"]\n   :extra-deps  {com.cognitect/test-runner\n                {:git/url \"https://github.com/cognitect-labs/test-runner.git\"\n                 :git/sha     \"f7ef16dc3b8332b0d77bc0274578ad5270fbfedd\"}}\n     :main-opts   [\"-m\" \"cognitect.test-runner\"]}\n}\n</code></pre>"},{"location":"clojure-cli/defining-aliases/#clojure-exec-tool","title":"Clojure Exec tool","text":"<p>With Clojure CLI tools version 1.10.1.697 the <code>-X</code> flag was introduced using aliases with Clojure exec.</p> <p>The configuration should define a fully qualified function that runs the tool.</p> <p>The function should take arguments as key/value pairs as with an Edn hash-map, rather than relying on positional arguments as strings.</p> <p>In this example, <code>:exec-fn</code> defines the fully qualified function name that will be called.  <code>:exec-args</code> is a hash-map of the default key values pairs that are passed to the function as an argument.</p> <pre><code>  :project/new\n  {:replace-deps {seancorfield/clj-new {:mvn/version \"1.1.23\"}}\n   :main-opts    [\"-m\" \"clj-new.create\"]    ;; deprecated\n   :exec-fn      clj-new/create\n   :exec-args    {:template lib :name practicalli/playground}\n   }\n</code></pre> <p>Default arguments can be over-ridden in the command,  e.g. <code>clojure -X:project/new :template app :name practicalli/simple-application</code> uses a different template</p> <p>Additional arguments can be sent when running the command, e.g. <code>clojure -X:project/new :template figwheel-main :name practicalli/landing-page :args '[\"--reagent\"]'</code> uses the <code>figwheel-main</code> template, specifies a name and <code>:args</code> arguments sent to</p> <p><code>:ns-default</code> can also be used to qualify the function that will be executed in an alias.  <code>:ns-default</code> is especially useful when there are several functions that could be called from the specific namespace.</p> <p>The command line can over-ride the <code>:exec-fn</code> function configuration, allowing for a default configuration that can be easily over-ridden.</p> <p>Example</p> <pre><code>  :project/new\n  {:replace-deps {seancorfield/clj-new {:mvn/version \"1.1.226\"}}\n   :main-opts    [\"-m\" \"clj-new.create\"]    ;; deprecated\n   :ns-default   clj-new\n   :exec-fn      create\n   :exec-args    {:template lib :name practicalli/playground}\n   }\n</code></pre> <p>Keyword naming</p> <p>Alias names are a Clojure keyword, which can be qualified to provide context, e.g. <code>:project/create</code>.  </p> <p>Aliases are composable (chained together) and their path and deps configurations merged:</p> <pre><code>clojure -M:task/path:task/deps:build/options\n</code></pre> <p>When multiple aliases contain a <code>:main-opts</code> configurations they are not merged, the configuration in the last alias is used</p>"},{"location":"clojure-cli/defining-aliases/#resources","title":"Resources","text":"<p>clj-exec: insideclojure.org clj-exec update: insideclojure.org Clojure CLI execution options Tips for designing aliases</p>"},{"location":"clojure-cli/design-journal/","title":"Design Journal","text":"<p>A design journal captures with code and comments the decisions taken for a project, invaluable to anyone trying to get up to speed with a project.</p>"},{"location":"clojure-cli/design-journal/#using-a-design-journal-namespace","title":"Using a design-journal namespace","text":"<p>A single namespace encourages the journal to flow as the design of the application flows.  So onboarding onto a project is essentially reading and evaluating code from top to bottom.</p>"},{"location":"clojure-cli/design-journal/#using-comment-blocks","title":"Using comment blocks","text":"<p>It is useful to include examples of how you expect key parts of the system to be called and the kind of arguments they receive.  Placing these examples in a (comment ,,,) expression ensures they are not accidentally evaluated whilst showing the most important function calls in a particular namespace.</p>"},{"location":"clojure-cli/execution-options/","title":"Clojure CLI Execution options","text":"<p>Execution options (<code>-A</code> <code>-M</code> <code>-P</code> <code>-T</code> <code>-X</code>) define how aliases are used with the Clojure CLI. Aliases are included via one of these execution options and each option can affect how the alias is used.</p> Clojure CLI design evolution <p>The first documented released used the <code>-A</code> execution option to include aliases. </p> <p>The design has evolved to provide specific execution options to run code via clojure.main (<code>-M</code>) and clojure.exec (<code>-X</code>). </p> <p>In July 2021 the ability to run tools (<code>-T</code>) independent from the Clojure project classpath was introduced.</p>"},{"location":"clojure-cli/execution-options/#quick-summary","title":"Quick summary","text":"<p><code>-M</code> uses <code>clojure.main</code> to call the <code>-main</code> function of the specified namespace, passing string-based arguments.</p> <p><code>-X</code> uses <code>clojure.exec</code> to call a fully qualified function, passing arguments as key and value pairs</p> <p><code>-T</code> runs a tool independent from project dependencies.  Only the libraries in the alias are included in the Class Path.  The path is defined as <code>\".\"</code> by default.</p> <p><code>-P</code> downloads library dependencies, including those from specified aliases</p> <p><code>-A</code> in the specific case of running a basic terminal UI REPL with the <code>clojure</code> command or <code>clj</code> wrapper.</p>"},{"location":"clojure-cli/execution-options/#clojuremain","title":"clojure.main","text":"<p><code>-M</code> flag instructs Clojure CLI tools to use <code>clojure.main</code> to run Clojure code.</p> <p>The <code>--main</code> or <code>-m</code> flag is an argument to <code>clojure.main</code> which specifies the namespace to search for a <code>-main</code> function.</p> <p><code>clojure.main/main</code> function searches for a <code>-main</code> function in the given namespace, e.g. <code>--main pracicalli.gameboard.service</code></p> <p>If the -main function is not found or the namespace is not specified, then the <code>clojure</code> command will run a REPL session.</p> <p>Run a project with the main namespace <code>practicalli.sudoku-solver</code>, without any additional aliases on the command line</p> <pre><code>clojure -M -m practicalli.sudoku-solver\n</code></pre> <p>Add <code>:project/run</code> alias to the project <code>deps.edn</code> file to provide a simpler way to run the project on the command line</p> <pre><code>:project/run {:main-opts [\"--main\" \"practicalli.sudoku-solver\"]}\n</code></pre> <p>Now the project code can be run using the simple command line form</p> <pre><code>clojure -M:project/run\n</code></pre>"},{"location":"clojure-cli/execution-options/#using-clojuremain","title":"Using clojure.main","text":"<p><code>clojure.main</code> namespace has been the way Clojure code was run (including a REPL) for most of its history.  This is now evolving with the addition of clojure.exec. clojure.main has other features, as covered in the REPL and main entrypoints article) on clojure.org.</p>"},{"location":"clojure-cli/execution-options/#rebel-rich-terminal-ui","title":"Rebel rich terminal UI","text":"<p>Rebel readline provides a terminal UI REPL, providing auto-completion, function signatures, documentation, etc.</p> <p><code>:repl/rebel</code> is an alias that includes nrepl, cider-nrepl and rebel-readline libraries, with a <code>:main-opts</code> to run the <code>rebel-readline.main/-main</code> function via <code>clojure.main</code>.</p> <pre><code>:repl/rebel\n{:extra-deps {nrepl/nrepl                {:mvn/version \"0.9.0\"}\n              cider/cider-nrepl          {:mvn/version \"0.28.2\"}\n              com.bhauman/rebel-readline {:mvn/version \"0.1.4\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n</code></pre> <p>Use the <code>:repl/rebel</code> alias with the <code>-M</code> execution option</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Multiple aliases can be specified to include additional paths and libraries. Aliases chained together have their configuration merged</p> <p><code>:env/dev</code> adds \"dev\" as an extra path, with the <code>dev/user.clj</code> file automatically loading its code into the <code>user</code> namespace when the REPL starts</p> <p><code>:lib/hotload</code> alias adds the <code>org.clojure/tools.deps.alpha</code> library to provide hotloading of dependencies into the running REPL</p> <p>Start a REPL process with this alias</p> <pre><code>clojure -M:env/dev:lib/hotload:repl/rebel\n</code></pre> <p>The Rebel REPL UI will start, include the dev directory on the class path and the <code>org.clojure/tools.deps.alpha</code> library loaded into the REPL</p>"},{"location":"clojure-cli/execution-options/#chaining-aliases","title":"Chaining aliases","text":"<p>Alises can be used together by chaining their names on the command line</p> <pre><code>clojure -M:env/dev:lib/hotload:repl/rebel\n</code></pre> <p>The <code>clojure</code> command will merge the <code>:extra-paths</code> and <code>:extra-deps</code> values from each alias in the chain.</p> <p>The <code>:main-opts</code> values from the aliases are not merged. Only the <code>:main-opts</code> value from the last alias in the chain is used with <code>clojure.main</code> to run the Clojure code.</p> <p>If the command line includes the <code>-m</code> flag with a namespace, then that namespace is passed to <code>clojure.main</code>, ignoring all <code>:main-opts</code> values from the aliases.  The <code>-i</code> and <code>-e</code> flags for clojure.main also replace <code>:main-opts</code> values.</p>"},{"location":"clojure-cli/execution-options/#clojureexec","title":"clojure.exec","text":"<p><code>-X</code> flag provides the flexibility to call any fully qualified function, so Clojure code is no longer tied to <code>-main</code></p> <p>Any function on the class path can be called and is passed a hash-map as an argument.  The argument hash-map is either specified in an alias using <code>:exec-args</code> or assembled into a hash-map from key/value pairs on the command line.  Key/values from the command line are merged into the <code>:exec-args</code> map if it exists, with the command line key/values taking precedence.</p>"},{"location":"clojure-cli/execution-options/#clojureexec-arguments","title":"clojure.exec arguments","text":"<p>Clojure.exec command takes key value pairs read as EDN values (extensible data notation that is the base syntax of Clojure).</p> <p>Number values and keywords can be parsed from the command line</p> <p>Arguments that are vectors and hash maps should be wrapped in single quotes to avoid the command line shell splitting arguments at spaces, e.g. <code>'[:a :b]'</code>, <code>'{:c 1}'</code>.</p> <p>The double quotes in an EDN string must be wrapped by single quotes, along with vectors and hash-maps</p> <ul> <li><code>'\"strings in double quotes surround by single quotes\"'</code></li> <li><code>'[:vectors :with-single-quotes]'</code></li> <li><code>'{:hash-maps :with-single-quotes}'</code></li> </ul>"},{"location":"clojure-cli/execution-options/#clojureexec-examples","title":"clojure.exec examples","text":"<p>Call the <code>status</code> function from the namespace <code>practicalli.service</code>, which is on the classpath in the practicalli.service project</p> <pre><code>clojure -X practicalli.service/status\n</code></pre> <p>Pass arguments to a <code>start</code> function in the <code>practicalli.service</code> namespace</p> <pre><code>clojure -X practicalli.service/start :port 8080 :join? false\n</code></pre> <p>As the arguments are key/value pairs, it does not matter in which order the pairs are used in the command line.</p>"},{"location":"clojure-cli/execution-options/#built-in-functions","title":"Built in functions","text":"<p>Clojure CLI tools has some built in tools under the special <code>:deps</code> alias (not to be confused with the <code>:deps</code> configuration in a <code>deps.edn</code> file)</p> <ul> <li><code>-X:deps mvn-install</code> - install a maven jar to the local repository cache</li> <li><code>-X:deps find-versions</code> - Find available versions of a library</li> <li><code>-X:deps prep</code> - prepare source code libraries in the dependency tree</li> </ul> <p>See <code>clojure --help</code> for an overview or <code>man clojure</code> for detailed descriptions</p>"},{"location":"clojure-cli/execution-options/#run-a-tool","title":"Run a Tool","text":"<p><code>-T</code> install, run and remove a tool, by the tool name or an alias.</p> <p>The <code>-T</code> execution option also uses the <code>clojure.exec</code> approach, although the <code>:deps</code> and <code>:path</code> values from a project <code>deps.edn</code> file are ignored.  This isolates the tool from the dependencies in a Clojure project.</p> <p>Calling Tools on the command line has the general form:</p> <pre><code>clojure -Ttool-name function-name :key \"value\" ,,,\n</code></pre> <p>A tool may provide many functions, so the specific function name is provided when calling the tool.</p> <p>key/value pairs can be passed as arguments to that function (as with the -X execution option)</p> <p><code>-Ttools</code> is a built-in tool to <code>install</code> and <code>remove</code> other tools, with the <code>:as</code> directive providing a specific name for the tool.</p> <p>In this example, the antq tool is installed using the name <code>antq</code></p> <pre><code>clojure -Ttools install com.github.liquidz/antq '{:git/tag \"1.3.1\"}' :as antq\n</code></pre> <p>Installing a tool adds an EDN configuration file using the name of the tool in <code>$XDG_HOME/.clojure/tools/</code> or <code>$HOME/.clojure/tools/</code> directory.</p> <p>Once a tool is installed, run by using the name of the tool.</p> <pre><code>clojure -Tantq outdated\n</code></pre> <p>Options to the tool are passed as key/value pairs (as the tool is called by clojure.exec)</p> <pre><code>clojure -Tantq outdated :upgrade true\n</code></pre> <p><code>-Ttools remove</code> will remove the configuration of the tool of the given name</p> <pre><code>clojure -Ttools remove :tool antq\n</code></pre>"},{"location":"clojure-cli/execution-options/#tools-install-or-aliases","title":"Tools install or aliases","text":"<p>Tools can also be defined in an alias with <code>:exec-fn</code> can be run via <code>-T:alias-name</code> as they are both executed using <code>clojure.exec</code>.</p> <p><code>-X</code> execution option can emulate <code>-T</code> behaviour when an alias uses <code>:replace-paths</code> and <code>:replace-deps</code> keys, instead of <code>:extra-paths</code> and <code>:extra-deps</code>, so project paths and dependencies are not included loaded by the alias.</p> <p>Using an alias for a tool has the advantage allowing a use to define their preferred default arguments that are passed to the <code>:exec-fn</code>, using the <code>:exec-args</code> key.</p> <p>Default arguments could be included in the <code>deps.edn</code> of the installed tool itself, although this is controlled by the developer of that tool project.</p> <p>The <code>:search/outdated</code> alias defined in the <code>practicalli/clojure-deps-edn</code> user level configuration is an example of a tool alias with default arguments</p> <pre><code>  :search/outdated\n  {:replace-paths [\".\"]\n   :replace-deps  {com.github.liquidz/antq {:mvn/version \"1.3.1\"}\n                   org.slf4j/slf4j-nop     {:mvn/version \"1.7.32\"}}\n   :main-opts     [\"-m\" \"antq.core\"]\n   :exec-fn antq.tool/outdated\n   :exec-args {:directory [\".\"] ; default\n               :exclude [\"com.cognitect/rebl\"\n                         \"org.openjfx/javafx-base\"\n                         \"org.openjfx/javafx-controls\"\n                         \"org.openjfx/javafx-fxml\"\n                         \"org.openjfx/javafx-swing\"\n                         \"org.openjfx/javafx-web\"]\n               ;; :focus [\"com.github.liquidz/antq\"]\n               :skip [\"boot\" \"leiningen\"]\n               :reporter \"table\" ; json edn format\n               :verbose false\n               :upgrade false\n               :force   false}}\n</code></pre> <p>This alias is called using <code>clojure -T:search/outdated</code> and is the same as calling <code>clojure -Tantq outdated ,,, ,,,</code> with a long list of key value options that represent the arguments in the alias.</p> <p>As the output is a table of results, the command output is typically pushed to a file: <code>clojure -T:search/outdated &gt; outdated-2021-12-24.txt</code></p> <p>Example tools include</p> <ul> <li>liquidz/antq - search dependencies for newer library versions</li> <li>seancorfield/deps-new - create new projects using templates</li> <li>clojure-nvd - check dependencies against National Vunerability Database</li> </ul>"},{"location":"clojure-cli/execution-options/#prepare-dependencies","title":"Prepare dependencies","text":"<p><code>-P</code> flag instructs the <code>clojure</code> command to download all library dependencies to the local cache and then stop without executing a function call.</p> <p>The <code>-P</code> flag is often used with Continuous Integration workflows and to create pre-populated Container images, to avoid repeatedly downloading the same library jar files.</p> <p>If used with just a project, then the Maven dependencies defined in the project <code>deps.edn</code> file will be downloaded, if not already in the users local cache (<code>~/.m2/repository/</code>).</p> <p>If <code>:git</code> or <code>:local/root</code> dependencies are defined, the respective code will be downloaded and added to the classpath.</p> <p>Prepare flag by itself download dependencies defined in the <code>:deps</code> section of the <code>deps.edn</code> file of the current project.</p> <pre><code>clojure -P\n</code></pre> <p>Including one or more aliases will preparing all the dependencies from every alias specified</p> <pre><code>clojure -P -M:env/dev:lib/hotload:repl/cider\n</code></pre> <p><code>-P</code> flag must be used before any subsequent arguments, i.e. before <code>-M</code>, <code>-X</code>, <code>-T</code></p> <p>As prepare is essentially a dry run, then the <code>clojure</code> command does not call <code>:main-opts</code> or <code>:exec-fn</code> functions, even if they exist in an alias or on the command line.</p> <p><code>-P</code> will warn if a project has dependencies that require building from source (i.e Java code) or resource file manipulation.  If so then <code>clojure -X:deps prep</code> will prepare these source based dependencies.</p>"},{"location":"clojure-cli/execution-options/#built-in-terminal-ui-repl","title":"Built-in terminal UI REPL","text":"<p><code>-A</code> is stated as the official way to include an alias when running a REPL terminal UI <code>clojure</code> or <code>clj</code>.</p> <p>Practicalli recommends using Rebel Readline which uses -M execution option, so -A execution option is rarely used by Practicalli.</p> <p>The <code>:env/dev</code> alias adds \"dev\" directory to the class path, typically used to add a <code>user.clj</code> that will automatically load code from the <code>user</code> namespace defined in that file.</p> <pre><code>clojure -A:env/dev\n</code></pre> <p>The alias definition is <code>:env/dev {:extra-paths [\"dev\"]}</code></p> <p>Aliases can be chained together and their configuration will be merged</p> <p><code>:lib/hotload</code> adds a dependency to provide hotloading of other dependencies</p> <pre><code>:lib/hotload\n{:extra-deps {org.clojure/tools.deps.alpha\n                {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                 :sha     \"d77476f3d5f624249462e275ae62d26da89f320b\"}\n              org.slf4j/slf4j-nop {:mvn/version \"1.7.32\"}}}\n</code></pre> <p>Start a REPL process with this alias</p> <pre><code>clojure -A:env/dev:lib/hotload\n</code></pre> <p>Use -M for alias definitions including :main-opts</p> <p>Using an alias that contains a <code>:main-opts</code> key with <code>-A</code> will fail to run a REPL and print a warning to use <code>-M</code> execution option The <code>:main-opts</code> configuration for <code>-A</code> execution option is deprecated (although currently works in 1.10.x). To run Clojure code via <code>clojure.main</code> the <code>-M</code> option should be with aliases that includes <code>:main-opts</code>.</p>"},{"location":"clojure-cli/execution-options/#summary","title":"Summary","text":"<p>There are many options when it comes to running Clojure CLI tools that are not covered here, however, this guide gives you the most common options used so far.</p> <p>Practicalli recommends using the <code>-X</code> execution option where possible, as arguments follow the data approach of Clojure design.</p> <p>The <code>-J</code> and <code>:jvm-opts</code> are useful to configure the Java Virtual machine and deserve an article to themselves as there are many possible options.</p> <p>The <code>-T</code> tools is an exciting and evolving approach and it will be interesting to see how the Clojure community adopt this model.</p> <p>See the Deps and CLI Reference Rationale for more details and description of these options.</p>"},{"location":"clojure-cli/execution-options/#references","title":"References","text":"<ul> <li>Inside Clojure - clj exec</li> <li>Inside Clojure - clj exec update</li> </ul>"},{"location":"clojure-cli/practicalli-config/","title":"Practicalli Clojure CLI Configuration","text":"<p> Practicalli Clojure CLI Config</p> <p> Practicalli Clojure CLI Config is a user configuration for Clojure CLI tools providing a range of community tools via meaningful aliases, supporting Clojure and ClojureScript development.</p> <p>Alias names are designed with qualified keywords that provide context for the use of an alias (<code>env</code>, <code>inspect</code>, <code>project</code>, <code>repl</code>, <code>search</code> <code>test</code>). These keywords help with discovery and reduce cognitive load required to remember their purpose.</p> <p>Commonly used arguments are included in many alias via <code>:main-opts</code> or <code>:exec-args</code> which can be overridden on the command line.</p> Minimum Clojure CLI Version - 1.10.3.1040 <p>Clojure CLI version 1.10.3.1040 is the minimum version, although the latest available version is recommended.</p> <p>Check the version of Clojure CLI currently installed via <code>clojure --version</code> or <code>clojure -Sdescribe</code></p> Remote Environments or Continuous Integration <p>For remote environments or Continuous Integration services, include  Practicalli Clojure CLI Config) in the environment build or copy specific aliases to the Clojure project <code>deps.edn</code> configuration.</p>"},{"location":"clojure-cli/practicalli-config/#install","title":"Install","text":"<p>Fork or clone  Practicalli Clojure CLI Config GitHub repository, first removing the <code>$XDG_CONFIG_HOME/clojure</code> or <code>$HOME/.clojure</code> directory if they exist.</p> Check Clojure CLI configuration location <p>Check the location of your Clojure configuration directory by running <code>clojure -Sdescribe</code> and checking the <code>:user-config</code> value.</p> Free Desktop XDG CONFIGClassic Config <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, clone the repository to <code>$XDG_CONFIG_HOME/clojure</code></p> <pre><code>git clone https://github.com/practicalli/clojure-deps-edn.git $XDG_CONFIG_HOME/clojure\n</code></pre> <p>Clojure CLI will look for its configuration in <code>$HOME/.clojure</code> directory if <code>$XDG_CONFIG_HOME</code> and <code>CLJ_CONFIG</code> environment variables not set.</p> <pre><code>git clone https://github.com/practicalli/clojure-deps-edn.git $HOME/.clojure\n</code></pre>"},{"location":"clojure-cli/practicalli-config/#community-tools","title":"Community Tools","text":"<p>The Clojure configuration directory contains a <code>deps.edn</code> file containing a substantial <code>:aliases</code> section with a long list of aliases.  These aliases are described in the  README of the project.</p> <p>All tools are provided via libraries and are only installed on first use.  Unused aliases will therefore not install their libraries.</p> <p>Aliases to start with</p> <p>Start with the following aliases to keep things simple</p> <p><code>clojure -T:project/create :name domain/project-name</code> to create a new clojure project</p> <p><code>clojure -M:repl/reloaded</code> to run a fully loaded REPL and rich terminal UI (which can be connected to from Clojure editors)</p> <p><code>clojure -X:test/watch</code> to run tests on file save (or <code>:test/run</code> to manually run tests once)</p> <p>Use Clojure tools.build to create jar and uberjar packages of the project.</p>"},{"location":"clojure-cli/practicalli-config/#repl-experience","title":"REPL experience","text":"<p>Rebel REPL terminal UI provides a feature rich REPL prompt experience, far beyond the basic <code>clj</code> command.</p> Command Description <code>clojure -M:repl/rebel</code> Rebel terminal UI <code>clojure -M:env/dev:repl/rebel</code> Rebel including deps &amp; path from <code>:env/dev</code> alias to configure REPL start <code>clojure -M:repl/reloaded</code> Rebel with <code>dev</code> &amp; <code>test</code> paths, library hotload, namespace reload, portal data inspector <code>clojure -M:repl/rebel-cljs</code> Run a ClojureScript REPL using Rebel Readline <p><code>:repl/help</code> in the REPL for help and available commands.  <code>:repl/quit</code> to close the REPL.</p>"},{"location":"clojure-cli/practicalli-config/#clojure-projects","title":"Clojure Projects","text":"<ul> <li>Create Clojure CLI specific projects using deps-new</li> <li>Create projects from deps, leiningen and boot templates with clj-new</li> </ul> Command Description <code>clojure -T:project/create</code> library project called playground <code>clojure -T:project/create :template app :name practialli/service</code> Clojure CLI project from app template <code>clojure -T:project/new :template luminus :name practicalli/full-stack-app +http-kit +h2</code> Luminus project with given name and template options"},{"location":"clojure-cli/practicalli-config/#run-projects","title":"Run projects","text":"<p>Run project with or without an alias:</p> <pre><code>clojure -M:alias -m domain.app-name\nclojure -M -m domain.app-name\n</code></pre> <p>The <code>-M</code> flag is required even if an alias is not included in the running of the application.  A warning will be displayed if the <code>-M</code> option is missing.</p> <p>In the project deps.edn file it could be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.</p> <pre><code>:project/run\n{:ns-default domain.main-namespace\n :exec-fn -main\n :exec-args {:port 8888}}\n</code></pre> <p>Then the project can be run using <code>clojure -X:project/run</code> and arguments can optionally be included in this command line, to complement or replace any default arguments in <code>exec-args</code>.</p>"},{"location":"clojure-cli/practicalli-config/#project-dependencies","title":"Project dependencies","text":"Command Description <code>clojure -M:project/errors</code> detailed report of compilation errors for a project <code>clojure -M:search/libraries library-name</code> fuzzy search Maven &amp; Clojars <code>clojure -M:search/libraries -F:merge library-name</code> fuzzy search Maven &amp; Clojars and save to project deps.edn <code>clojure -M:search/outdated</code> report newer versions for maven and git dependencies <code>clojure -M:search/unused-vars</code> search and remove unused vars"},{"location":"clojure-cli/practicalli-config/#project-deployment","title":"Project Deployment","text":"<p>Deploy a project archive file locally or to Clojars.org</p> <p>Package projects into jars using tools.build</p> <p>Clojure tools.build is the recommended way to create library jar files and application Uberjar files.</p> Command Description <code>clojure -X:deps mvn-install project.jar</code> [NEW] deploy jar file to local maven repository, i.e. <code>~/.m2/repository</code> <code>clojure -M:project/clojars project.jar</code> deploy jar file to Clojars <code>clojure -M:project/clojars-signed project.jar</code> deploy signed jar file to Clojars <p>Set Clojars username/token in <code>CLOJARS_USERNAME</code> and <code>CLOJARS_PASSWORD</code> environment variables.</p> <p>Set fully qualified artifact-name and version in project <code>pom.xml</code> file</p> <p>Path to project.jar can also be set in alias to simplify the Clojure command.</p> <p><code>clojure -X:deps mvn-install project.jar</code> for local deployment of jars is part of the 1.10.1.697 release of the Clojure CLI tools in September 2020.</p>"},{"location":"clojure-cli/practicalli-config/#java-sources","title":"Java Sources","text":"<p>Include Java source on the  classpath to look up Java Class and method definitions, e.g. <code>cider-find-var</code> in Emacs Requires: Java sources installed locally (e.g. \"/usr/lib/jvm/openjdk-11/lib/src.zip\")</p> <ul> <li><code>:lib/java17-source</code></li> </ul> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p>"},{"location":"clojure-cli/practicalli-config/#format-tools","title":"Format tools","text":"<p>Use formatting tools to support a consistent code style across all Clojure projects</p> Command Description <code>clojure -M:format/cljstyle check / fix</code> Check or fix code style (cljstyle) <code>clojure -M:format/cljfmt check / fix</code> Check or fix code style (cljfmt) <code>clojure -M:format/zprint filename</code> Format file using zprint <p>Include <code>:lib/pprint-sorted</code> when starting a REPL to pretty print data with sorted keys and set values</p>"},{"location":"clojure-cli/practicalli-config/#databases-and-drivers","title":"Databases and drivers","text":"<p>Databases and drivers, typically for development time inclusion such as embedded databases</p> <ul> <li><code>:database/h2</code> - H2 embedded database library and next.jdbc</li> <li><code>lib/next.jdbc</code> - include the next.jdbc library</li> </ul> <p><code>clojure -M:database/h2</code> - run a REPL with an embedded H2 database and next.jdbc libraries</p> <p>https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/doc/getting-started#create--populate-a-database</p> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p>"},{"location":"clojure-cli/practicalli-config/#data-science","title":"Data Science","text":"<ul> <li><code>lib/clerk</code> - Clerk Notebooks</li> </ul>"},{"location":"clojure-cli/practicalli-config/#visualizing-projects","title":"Visualizing projects","text":"<p>Create Graphviz graphs of project and library dependencies</p> <p>Morpheus creates grahps of project vars and their relationships</p> <ul> <li><code>:graph/vars</code> - generate graph of vars in a project as a .dot file</li> <li><code>:graph/vars-png</code> - generate graph of vars in a project as a .png file using <code>src</code> and <code>test</code> paths</li> <li><code>:graph/vars-svg</code> - generate graph of vars in a project as a .svg file using <code>src</code> and <code>test</code> paths</li> </ul> <p>Install Graphviz to generate PNG and SVG images.  Or use the Edotor website to convert .dot files to PNG or SVG images and select different graph layout engines.</p> <p>Vizns creates graphs of relationships between library dependencies and project namespaces</p> <ul> <li><code>:graph/deps</code></li> <li><code>:graph/deps-png</code> - generate a single deps-graph png image</li> </ul> <p>Other options: - <code>clojure -M:graph/deps navigate</code>  # navigable folder of SVGs - <code>clojure -M:graph/deps single</code>    # deps-graph.dot file - <code>clojure -M:graph/deps single -o deps-graph.png -f png</code> - <code>clojure -M:graph/deps single -o deps-graph.svg -f svg</code> - <code>clojure -M:graph/deps single --show</code>  # View graph without saving</p>"},{"location":"clojure-cli/practicalli-config/#data-inspector","title":"Data Inspector","text":"<p>Portal Navigate data in the form of edn, json and transit</p> <p>Practicalli Clojure - data browsers section - portal</p> Command Description <code>clojure -M:inspect/portal-cli</code> Clojure REPL with Portal dependency <code>clojure -M:inspect/portal-web</code> ClojureScript web browser REPL with Portal dependency <code>clojure -M:inspect/portal-node</code> ClojureScript node.js REPL with Portal dependency <p>Using Portal once running</p> <p><code>(require '[portal.api :as portal])</code> once the REPL starts.  For <code>inspect/portal-web</code> use <code>(require '[portal.web :as portal])</code> instead</p> <p><code>(portal/open)</code> to open the web based inspector window in a browser.</p> <p><code>(portal/tap)</code>to add portal as a tap target (add-tap)</p> <p><code>(tap&gt; {:accounts [{:name \"jen\" :email \"jen@jen.com\"} {:name \"sara\" :email \"sara@sara.com\"}]})</code> to send data to the portal inspector window (or any other data you wish to send)</p> <p><code>(portal/clear)</code> to clear all values from the portal inspector window.</p> <p><code>(portal/close)</code> to close the inspector window.</p>"},{"location":"clojure-cli/practicalli-config/#clojure-specification","title":"Clojure Specification","text":"<p>Clojure spec, generators and test.check</p> <ul> <li><code>:lib/spec-test</code> - generative testing with Clojure test.check</li> <li><code>:lib/spec2</code> - experiment with the next version of Clojure spec - alpha: design may change</li> </ul>"},{"location":"clojure-cli/practicalli-config/#unit-testing-frameworks","title":"Unit Testing frameworks","text":"<p>Unit test libraries and configuration.  The Clojure standard library includes the <code>clojure.test</code> namespace, so no alias is required.</p> <ul> <li><code>:test/env</code> - add <code>test</code> directory to classpath</li> <li><code>:lib/expectations</code> - <code>clojure.test</code> with expectations</li> <li><code>:lib/expectations-classic</code> - expectations framework</li> </ul> <p>Use expectations in a project <code>clojure -M:test:expectations</code> or from the command line with a test runner, e.g. <code>clojure -M:lib/expectations:test/runner</code></p>"},{"location":"clojure-cli/practicalli-config/#test-runners-and-test-coverage","title":"Test runners and Test Coverage","text":"<p>Tools to run unit tests in a project which are defined under <code>test</code> path.</p> <p>Run clojure with the specific test runner alias: <code>clojure -M:test-runner-alias</code></p> Command Description <code>clojure -M:test/run</code> Kaocha test runner for Clojure <code>clojure -M:test/watch</code> Kaocha: watch for changes <code>clojure -M:test/cljs</code> Kaocha test runner for ClojureScript"},{"location":"clojure-cli/practicalli-config/#lint-tools","title":"Lint tools","text":"<p>Static analysis tools to help maintain code quality and suggest Clojure idioms.</p> Command Description <code>clojure -M:lint/clj-kondo</code> comprehensive and fast static analysis lint tool <code>clojure -M:lint/eastwood</code> classic lint tool for Clojure <code>clojure -M:lint/idiom</code> Suggest idiomatic Clojure code"},{"location":"clojure-cli/practicalli-config/#performance-testing","title":"Performance testing","text":"<p><code>:performance/benchmark</code> alias includes the Criterium library for performance testing of Clojure expressions.</p> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p> <p><code>:dev/reloaded</code> and <code>:repl/reloaded</code> both include criterium library</p> <p>Start a REPL using the <code>:repl/reloaded</code> alias, or by including the <code>:performance/benchmark</code> in a Clojure command to start a REPL.</p> Repl Reloaded <p>```shell clojure -M:repl/reloaded</p> <p>```</p> Clojure command <p>```shell clojure -M:performance/benchmark:repl/basic</p> <p>```</p> REPL <p>Require the Criterium <code>quick-bench</code> function</p> <pre><code>(require '[criterium.core :refer [quick-bench]])\n</code></pre> <pre><code>(quick-bench (adhoc-expression))\n</code></pre> <p>Performance test a project in the REPL</p> <pre><code>clojure -M:performance/benchmark:repl/rebel\n\n(require '[practicalli/namespace-name]) ; require project code\n(in-ns 'practicalli/namespace-name)\n(quick-bench (project-function args))\n</code></pre> <p>Use the aliases with either <code>-M</code> or <code>-X</code> flags on the Clojure command line.</p> <p>In the REPL:</p> <pre><code>  (require '[clj-memory-meter.core :as memory-meter])\n   (memory-meter/measure (your-expression))\n</code></pre>"},{"location":"clojure-cli/repl-reloaded/","title":"Practicalli REPL Reloaded Workflow","text":"<p>An effective REPL workflow is central to Clojure development. Practicalli REPL Reloaded workflow provides a rich set of tools and minimises the need to restart the REPL</p> <ul> <li>custom REPL startup using <code>dev/user.clj</code></li> <li>continually run unit tests with Kaocha</li> <li>event log and publisher with mulog</li> <li> visualise &amp; navigate evaluation data and logs with Portal</li> <li>hotload libraries without restarting the REPL with <code>clojure.repl.deps</code> (Clojure 1.12)</li> <li>reload changed namespaces to manage large code refactor with <code>tools.namespace</code></li> <li>performance testing code expressions with time &amp; Criterium</li> </ul> <p></p>"},{"location":"clojure-cli/repl-reloaded/#start-the-repl","title":"Start the REPL","text":"<p>Start a Clojure REPL with the <code>:repl/reloaded</code> alias (or include <code>:dev/reloaded</code> alias in an Editor jack-in command or other REPL startup command).</p> <p>Aliases are defined in  Practicalli Clojure CLI Config</p> <p>Start a rich terminal UI repl and the REPL Reloaded tools</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>A  Rebel rich terminal UI REPL prompt provides direct evaluation in the REPL (with autocomplete, documentation, signature hints and multi-line editing)</p> <p>An nREPL server is started to allow connections from a range of Clojure editors.</p> <p>Portal Inspector window opens and is connected to all evaluation results and Mulog events that occur.</p> <p> Rebel REPL Teminal UI</p> Example Alias Definitions <p>Start a REPL process with an nREPL server to connect Clojure editors. Providing a Rebel rich terminal UI with tools to hotload libraries, reload namespaces and run Portal data inspector.  The alias also includes a path for custom REPL startup and a path to access unit test code, along with a test runner. <pre><code>:repl/reloaded\n{:extra-paths [\"dev\" \"test\"]\n :extra-deps {nrepl/nrepl                  {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl            {:mvn/version \"0.30.0\"}\n              com.bhauman/rebel-readline   {:mvn/version \"0.1.4\"}\n              djblue/portal                {:mvn/version \"0.35.1\"}\n              org.clojure/tools.namespace  {:mvn/version \"1.4.1\"}\n              org.slf4j/slf4j-nop          {:mvn/version \"2.0.6\"}\n              com.brunobonacci/mulog       {:mvn/version \"0.9.0\"}\n              lambdaisland/kaocha          {:mvn/version \"1.77.1236\"}\n              org.clojure/test.check       {:mvn/version \"1.1.1\"}\n              ring/ring-mock               {:mvn/version \"0.4.0\"}\n              criterium/criterium          {:mvn/version \"0.4.6\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n\n:dev/reloaded\n{:extra-paths [\"dev\" \"test\"]\n :extra-deps  {djblue/portal                {:mvn/version \"0.35.1\"}\n               org.clojure/tools.namespace  {:mvn/version \"1.4.1\"}\n               org.slf4j/slf4j-nop          {:mvn/version \"2.0.6\"}\n               com.brunobonacci/mulog       {:mvn/version \"0.9.0\"}\n               lambdaisland/kaocha          {:mvn/version \"1.77.1236\"}\n               org.clojure/test.check       {:mvn/version \"1.1.1\"}\n               ring/ring-mock               {:mvn/version \"0.4.0\"}\n               criterium/criterium          {:mvn/version \"0.4.6\"}}}\n</code></pre></p> <p>Include the <code>:dev/reloaded</code> or <code>:lib/hotload</code> aliases when starting the REPL with other aliases, using any of the available Clojure CLI execution options (<code>-A</code>,<code>-M</code>,<code>-X</code>,<code>-T</code>).</p> <p>Alias example from  Practicalli Clojure CLI Config</p> Clojure 1.11 Hotload Support <p>To support Clojure 1.11.x, add an <code>:lib/hotload</code> alias for the <code>clojure.tools.deps.alpha.repl</code> library using the latest SHA commit from the  add-libs3 branch of <code>clojure.tools.deps.alpha</code> library as an extra dependency.</p> <p>The <code>add-libs</code> code is on a separate , so requires the SHA from the head of add-libs3 branch</p> <p><pre><code>  :lib/hotload\n  {:extra-deps {org.clojure/tools.deps.alpha\n               {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> Include the <code>:dev/reloaded</code> or <code>:lib/hotload</code> aliases when starting the REPL with other aliases, using any of the available Clojure CLI execution options (<code>-A</code>,<code>-M</code>,<code>-X</code>,<code>-T</code>).</p> <p>Alias example from  Practicalli Clojure CLI Config</p>"},{"location":"clojure-cli/repl-reloaded/#custom-repl-startup","title":"Custom REPL startup","text":"<p>A Clojure REPL starts in the <code>user</code> namespace. When a <code>user.clj</code> file is on the classpath its code is loaded (evaluated) into the REPL during startup.</p> <p>Create a <code>dev/user.clj</code> file with libraries and tools to support development and add the <code>dev</code> directory to the classpath.</p> <p>Create a custom REPL Startup with dev/user.clj</p>"},{"location":"clojure-cli/repl-reloaded/#reload-namespaces","title":"Reload namespaces","text":"<p>As code and design evolves, expressions evaluated in the REPL may become stale especially when the names (symbols, vars) bound to function definitions are renamed or deleted from the source code.  Rather than restart the REPL process and loose all the state, one or more namespaces can be refreshed.</p> Remove function definitions before renaming <p>To minimise the need to reload namespaces, undefine function definitions (unbind their name to the function) before changing the names of the function.</p> <p>Remove a symbol from the namespace, using <code>*ns*</code> which is dynamically bound to the current namespace <pre><code>(ns-unmap *ns* 'function-or-def-name)\n</code></pre> Remove a specific namespace (any functions defined in the namespace are no longer accessible - illegalStateException - Attempting to call unbound function) <pre><code>(remove-ns 'practicalli.service.utils)\n</code></pre> Remove an alias for a specific namespace <pre><code>(ns-unalias 'practicalli.service.utils 'utils)\n</code></pre></p> <p>Clojure editors may provide commands to undefine a function definition, e.g. Emacs CIDER includes <code>cider-undef</code> to remove the current symbol via nREPL commands</p> <p>clojure.tools.namespace.repl contains the <code>refresh</code> function that compares source code files with the definitions in the REPL, removing and re-evaluating those namespaces containing changes.</p> <p>refresh will manage loading of namespaces with respect to their dependencies, ensuring each namespace can be loaded without error.</p> <p>Require the clojure.tools.namespace.repl refresh function</p> REPLProject <pre><code>(require '[clojure.tools.namespace.repl :refer [refresh]])\n</code></pre> <p>Use an ns form for the namespace (often added to a custom <code>user</code> namespace)</p> <pre><code>(ns user\n  (:require [clojure.tools.namespace.repl :refer [refresh]]))\n</code></pre> <p>Or in a rich comment expression</p> <pre><code>(comment\n  (require '[clojure.tools.namespace.repl :refer [refresh]]))\n</code></pre> <p>Refresh the namespaces that have saved changes</p> <pre><code>(refresh)\n</code></pre> <p>A list of refreshed namespaces are printed.  If there are errors in the Clojure code, then a namespace cannot be loaded and error messages are printed. Check the individual code expressions in the namespace to ensure they are correctly formed.</p> <p>Reload namespaces with dev/user.clj</p> Handling Errors <p>If an exception is thrown while loading a namespace, refresh stops and prints the namespace that caused the exception. (clojure.repl/pst) prints the rest of the stack trace</p> <p><code>*e</code> is bound to the exeception so will print the exeception when evaluated</p> tools.namespace refactor - documentation can be misleading <p><code>refresh</code> and other functions were moved to the <code>clojure.tools.namespace.repl</code> namespace. The original <code>clojure.tools.namespace</code> functions are deprecated, although the new <code>clojure.tools.namespace.repl</code> namespace is not deprecated.</p> <p>Clojure tools.namespace API reference Namespaces Reference - Clojure.org</p>"},{"location":"clojure-cli/repl-reloaded/#hotload-libraries","title":"Hotload Libraries","text":"<p><code>clojure.repl.deps</code> provides functions to hotload libraries into a running REPL, avoiding the need to restart the REPL and loose state just to use a new library with the project.</p> <ul> <li><code>add-lib</code> finds a library by name and adds it to the REPL</li> <li><code>add-libs</code> takes a hash-map of one or more library name and version key/value pairs and adds them to the REPL</li> <li><code>sync-deps</code> reads the project <code>deps.edn</code> file and adds <code>:deps</code> dependencies to the REPL that are not already loaded</li> </ul> <p>Hotload functions are typically called from a rich comment block in a separate <code>dev/user.clj</code> file to avoid being automatically loaded.</p> <p>Once hot-loaded, a library namespace can be required as if the dependency had been added to the project configuration before the REPL started.</p> <p>practicalli/clojure-webapp-hotload-libraries is an example project that uses REPL driven development and hot loading of libraries to build a very simple web server using http-kit and hiccup.</p> Hotload requires Clojure 1.12 &amp; latest Clojure CLI <p>Install the latest Clojure CLI version and use Clojure 1.12 onward to use the officially released hotload library.</p> <p><code>add-libs</code> is an unofficial feature for Clojure 1.11.x and available only in the add-libs3 branch of the now deprecated <code>clojure.tools.deps.alpha</code> library.</p> Hotload simple web server and build a page <pre><code>(comment\n  ;; Require if not automatically loaded by the REPL tooling, ie. Rebel Readline\n  #_(require '[clojure..deps.repl :refer [add-lib add-libs sync-deps]])\n\n  ;; hotload the libraries required for the server\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n\n  (require '[org.httpkit.server :as app-server])\n\n  ;; Discover which http-kit functions are available\n  (ns-publics (find-ns 'org.httpkit.server))\n\n  ;; Define an entry point for the application\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ) ; End of rich comment block\n</code></pre> <p>There are several approaches to hotload libraries, including via a terminal REPL UI or in a project with a Clojure editor:</p> <ul> <li>Rich terminal UI REPL</li> <li>Hotload in a Project</li> </ul>"},{"location":"clojure-cli/repl-reloaded/#unit-test-runner","title":"Unit test runner","text":"<p>Unit tests are written with <code>clojure.test</code> and reside in a parallel <code>test</code> directory, creating matching <code>_test.clj</code> files for each relevant clojure file under <code>src</code>.</p> <p>Test runners are highly configurable and can run a very specific set of tests, although Clojure is usually fast enough to run all the tests each time.</p> <p>Run the tests in a project with the kaocha test runner by issuing the following command in the root of the project.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Or continually watch for changes and run kaocha test runner each time a file is saved (typically in a separate terminal)</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Test run will stop on the first failed test unless <code>:fail-fast? false</code> is passed as an argument to either command.</p> Running Unit Tests in an Editor <p>Emacs and Neovim can run the kaocha test runner if one of the <code>:repl/reloaded</code>, <code>:dev/reloaded</code> or <code>:lib/kaocha</code> aliases are used to start the Clojure REPL.</p> <p>Emacs, Neovim and VS Code Calva also have their own built-in test runners. Test and source code must be evaluated in the REPL for the editor test runners to discover this code.  Editor test runners to not read code from the Clojure files in <code>src</code> or <code>test</code> directories.</p> <p>Writing Unit Tests for Clojure Using Test Runners with Projects</p>"},{"location":"clojure-cli/repl-reloaded/#performance-tests","title":"Performance tests","text":"<p><code>time</code> is a quick way to see if an expression is worth further performance investigation.</p> <p><code>(time ,,,)</code> wrapped around an expression will print the duration that expression took to run.  This provides a very rough indicator of the performance of code, although as it only runs once then results may vary and are easily affected by the environment (Java Virtual Machine, Operating System, other concurrent processes).</p> <p>Criterium provides more realistic performance results which are less affected by the environment, providing a better indication of performance to inform design choices.</p> <p>Criterium tools take a little longer to run in order to return more accurate and consistent performance results.</p> REPLProject <p>Require the criterium library <pre><code>(require '[criterium.core :as benchmark])\n</code></pre></p> <p>Require the criterium library via the ns expression</p> <p><pre><code>(ns user\n  (:require [criterium.core :as benchmark]))\n</code></pre> Or require the criterium library in a rich comment expression <pre><code>(comment\n  (require '[criterium.core :as benchmark]))\n</code></pre></p> <p>Wrap the <code>quick-bench</code> function around the expression to run performance testing upon</p> <pre><code>(benchmark/quick-bench ,,,)\n</code></pre> <p>The expression being tested will be called multiple times and the duration and average times will be printed.</p> <p>Criterium automatically adjusts the benchmark run time according to the execution time of the measured expression. If the expression is fast, Criterium will run it plenty of times, but if a single iteration is quite slow, it will be executed fewer times</p> <p>Use quick-bench rather than bench</p> <p>The bench macro is claimed to be more accurate than quick-bench, but in practice, it runs for much longer and doesn't yield significantly different results in most cases</p> <p>Criterium API Documentation Benchmark with Criterium article</p>"},{"location":"clojure-cli/repl-reloaded/#log-and-publish-events","title":"Log and publish events","text":"<p>mulog is a micro-logging library that logs events and data extremely fast and provides a range of publishers for log analysis.</p> <p>Use the mulog <code>log</code> function to create events to capture useful information about the Clojure system operation.  Publish the logs locally to a console or to a log analysis service such as zipkin or Grafana</p> REPLProject <p>Require the mulog library <pre><code>(require '[com.brunobonacci.mulog :as mulog])\n</code></pre></p> <p>Require the mulog library via the namespace form <pre><code>(ns your-ns\n  (:require [com.brunobonacci.mulog :as mulog]))\n</code></pre></p> <p>Optionally create an event global context, containing information that will be included in every event created</p> <pre><code>(mulog/set-global-context! {:service-name \"Practicalli GameBoard\", :version \"1.0.1\", :env \"dev\"})\n</code></pre> <p>Create events with an identity that contains key/value pairs of data that captures the desired information about the event.</p> <pre><code>(mulog/log ::system-started :version \"0.1.0\" :init-time 32)\n</code></pre> <p>Start a publisher to see all the events created.  The publisher can be to the console or to log analysis tools like zipkin or Grafana</p> <pre><code>(mulog/start-publisher! {:type :console})\n</code></pre> <p><code>trace</code> provides accurate data around instrumented operations of a single system or over a distributed system. trace data can be used in Elasticsearch and real-time streaming system sudh as Apache Kafka.</p> <p>trace will track the rate of a complex operation, including the outcome and latency, within the contextual information of that operation.</p> <p>Consider a function that calls several external services</p> <pre><code>(defn product-status [product-id]\n  (let [stock (http/get availability-service {:product-id product-id})\n        pricing (http/get pricing-service {:product-id product-id})]))\n</code></pre> <p>Create a trace between the function calls</p> <pre><code>(mulog/trace ::product-status\n  [:product-id product-id]\n  (product-status product-id))\n</code></pre> <p><code>trace</code> starts a timer then calls <code>(product-status product-id)</code>. Once the execution completes a log an event is created using <code>log</code> and uses the global context. By including the product id in the trace call, information is captured about the specific product involved in the trace log.</p> <pre><code>;; {:mulog/event-name :practicalli.service/products,\n;;  :mulog/timestamp 1587504242983,\n;;  :mulog/trace-id #mulog/flake \"4VTF9QBbnef57vxVy-b4uKzh7dG7r7y4\",\n;;  :mulog/root-trace #mulog/flake \"4VTF9QBbnef57vxVy-b4uKzh7dG7r7y4\",\n;;  :mulog/duration 254402837,\n;;  :mulog/namespace \"practicalli.service\",\n;;  :mulog/outcome :ok,\n;;  :app-name \"Practicalli GameBoard\",\n;;  :env \"dev\",\n;;  :version \"1.0.1\"}\n</code></pre>"},{"location":"clojure-cli/repl-reloaded/#trace-function-calls","title":"Trace function calls","text":"<p>clojure.tools.trace can trace values, functions and a whole namespace of functions.</p> <p>Tracing a value will show how that value flows through the code</p> <p>Tracing a function shows the arguments passed to the function each time it is called and the results.  Tracing will identify forms that are failing and also show the results of the function call, helping spotting unwanted <code>nil</code> arguments and parts of a function definition that is failing.</p> <ul> <li><code>trace</code> values, optionally assigning a tag</li> <li><code>trace-vars</code> dynamically trace a given fully qualified function</li> <li><code>untrace-vars</code> - remove trace from a given fully qualified function</li> <li><code>trace-ns</code> dynamically trace all functions in the given namespace</li> <li><code>untrace-ns</code> remove trace from all functions in the given namespace</li> </ul> <p><code>:repl/reloaded</code> and <code>:dev/reloaded</code> include the clojure.tools.trace dependency, i.e. <code>org.clojure/tools.trace {:mvn/version \"0.7.11\"}</code></p> <p>tools.trace API Reference</p> REPLProject <p>Require the <code>clojure.tools.trace</code> library and refer the <code>trace</code> and <code>untrace</code> functions <pre><code>(require '[clojure.tools.trace :as trace])\n</code></pre></p> <p>Require the <code>clojure.tools.trace</code> library using the alias <code>trace</code></p> <pre><code>(ns user\n  (:require '[clojure.tools.trace :as trace]))\n</code></pre> <p>To trace a value returned from an expression, optionally adding a tag</p> <pre><code>(trace/trace  \"increments\" (map inc [1 2 3 4 5]))\n;;=&gt; TRACE increments: (2 3 4 5 6)\n;;=&gt; (2 3 4 5 6)\n</code></pre> <p>Trace a function call and its return value</p> <pre><code>(deftrace random-function [namespace] (rand-nth (vals (ns-publics namespace))))\n</code></pre> <p>Call the function to see the output of trace</p> <pre><code>(random-function 'clojure.core)\n;;=&gt; TRACE t1002: (random-function 'clojure.core)\n;;=&gt; TRACE t1002: =&gt; #'clojure.core/iteration\n;;=&gt; #'clojure.core/iteration\n</code></pre> <p>Trace functions can identify which form is failing</p> <pre><code>(trace/trace-vars practicalli.random-function/random-number)\n;;=&gt; #'practicalli.random-function/random-number\n</code></pre> <p>Call the function that is being traced and see the error</p> <pre><code>(practicalli.random-function/random-number 42)\n;;=&gt; TRACE t10951: (practicalli.random-function/random-number 42)\n;;=&gt; Execution error (ArithmeticException) at practicalli.random-function/random-number (random_function.clj:17).\n;;=&gt; Divide by zero\n</code></pre> <p>Dynamically trace all functions in the given name space</p> <pre><code>(trace-ns domain.namespace)\n</code></pre> <p>Or remove all function traces in a namespace</p> <pre><code>(untrace-ns domain.namespace)\n</code></pre> <p>Dynamically trace a given function</p> <pre><code>(trace-vars domain.namespace/function-name)\n ```\n\nRemove the trace on a given function\n\n```clojure\n(untrace-vars domain.namespace/function-name)\n</code></pre>"},{"location":"clojure-cli/repl-startup/","title":"Configure REPL on Startup","text":"<p>A Clojure REPL starts in the <code>user</code> namespace and automatically loads common tools to support REPL based development. </p> <p>When interacting with the REPL prompt directly, use <code>require</code> expressions to include additional functions into the <code>user</code> nameapace rather than use potentially complex commands to set the namespace.</p> Clojure REPL only starts in user namespace <p>The Clojure REPL only guarantees startup in the <code>user</code> namespace. There is no specific mechanism to start the REPL in any other namespace than <code>user</code>.</p> <p>Clojure CLI could use the general <code>--eval</code> flag as a hack to set a different namespace with an <code>in-ns</code> expression, although this may affect other tools and add complexity to the startup process.</p> Default REPL Tools <p>The Clojure REPL automatically loads common tools to support the foundation of a REPL driven workflow:</p> <p> clojure.repl namespace loads:</p> <ul> <li> apropos - function names fuzzy matching a given regex pattern</li> <li> dir - sorted list of public vars (functions) in a given namespace</li> <li> doc - doc-string of a give Clojure function / symbol </li> <li> find-doc - doc-string of matching functions, given a string or regex pattern</li> <li> source - source code of a given function</li> <li> pst print stack trace, optionally setting depth</li> </ul> <p> clojure.java.javadoc loads  javadoc to show the doc-string of Java methods</p> <p> clojure.pprint namepace loads  pp &amp;  pprint to return pretty printed (human friendly format) evaluation results</p>"},{"location":"clojure-cli/repl-startup/#custom-user-namespace","title":"Custom user namespace","text":"<p>Add a custom <code>user</code> namespace to further enhance the Clojure REPL workflow:</p> <ul> <li>load code into the REPL by requiring namespaces</li> <li>call functions to start services that support development, e.g. logging publisher, print REPL command help menu</li> <li>launch development tools - e.g. portal data inspector</li> <li>start components (i.e for mount, component, integrant)</li> <li>hotload libraries into the REPL process without restart (Clojure 1.12 onward)</li> </ul> <p>Create a project with custom user namespace</p> <p>Projects created with  Practicalli Project Templates contain a <code>dev/user.clj</code> file for configuring the REPL at start up.</p> <p>Practicalli custom user namespace supports the  Practicalli REPL Reloaded workflow</p> <p>Start the REPL with either the <code>:dev/env</code>, <code>:dev/reloaded</code> or <code>:repl/reloaded</code> alias from  Practicalli Clojure CLI Config to include <code>dev</code> directory on the class path and automatically load <code>dev/user.clj</code> code on REPL startup.</p>"},{"location":"clojure-cli/repl-startup/#define-user-namespace","title":"Define user namespace","text":"<p>A custom <code>user.clj</code> is typically placed in a <code>dev</code> folder within the root of the project, with the <code>dev</code> path defined in an alias to keep it separated from production code.</p> <p>Create a <code>dev/user.clj</code> file with a namespace called <code>user</code>.</p> dev/user.clj<pre><code>(ns user)\n</code></pre> <p>Create an alias to include the <code>dev</code> path when running a REPL process</p>  Practicalli Clojure CLI ConfigManual <p> Practicalli Clojure CLI Config includes aliases that add <code>dev</code> directory to the class path</p> <ul> <li><code>:dev/env</code> alias only adds the <code>dev</code> directory to the classpath</li> <li><code>:dev/reloaded</code> adds library hotload, namespace reload, porta data inspector and testing libraries &amp; <code>test</code></li> <li><code>:repl/reloaded</code> adds Rebel rich terminal UI to the tools provided by <code>:dev/reloaded</code></li> </ul> <p>Add an alias to the user <code>deps.edn</code> configuration, i.e. <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code></p> <p>Clojure User Config<pre><code> :env/dev\n  {:extra-paths [\"dev\"]}\n</code></pre> Review  Practicalli Clojure CLI Config for further alias examples.</p> <p>Run a Clojure REPL with the <code>:repl/reloaded</code> alias (or <code>:dev/reloaded</code> <code>:dev/env</code>)  to add the <code>dev</code> directory to the class path and load the code in <code>dev/user.clj</code> file into the REPL.</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Keep <code>user.clj</code> separate</p> <p>The <code>user.clj</code> code should not be included in live deployments, such as a jar or uberjar.  Including the <code>dev/</code> directory via an alias separates the <code>user.clj</code> from deployment actions.</p>"},{"location":"clojure-cli/repl-startup/#requiring-namespaces","title":"Requiring namespaces","text":"<p>Namespaces required in the <code>user</code> ns form will also be loaded. If a required namespace also requires namespaces, they will also be loaded into the REPL during startup.</p> <p>Functions <code>(defn)</code> and data <code>(def)</code> are immediately available.</p> <p>Require namespace in user ns expression</p> <p>Add a require expression to the namespace definition in <code>dev/user.clj</code> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.project-namespace]))\n</code></pre></p> Requiring a large number of libraries may slow REPL start up time <p>Require namespace in require expression</p> <p>If the library is not always required, place a <code>require</code> within a <code>(comment ,,,)</code> expression to be evaluated by the developer any time after REPL startup. dev/user.clj<pre><code>(ns user)\n\n(comment\n  (require '[practicalli.project-namespace])\n#_())\n</code></pre></p>"},{"location":"clojure-cli/repl-startup/#calling-functions","title":"Calling functions","text":"<p>Use the fully qualified function name from the required namespace can be called, to start the application for example.</p> <p>Example</p> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.project-namespace]))\n\n(practicalli.project-namespace/-main)\n</code></pre> <p>An alias can be used in the require expression, useful if multiple functions from a namespace are to be called</p> <p>Example</p> dev/user.clj<pre><code>(ns user\n  (:require [practicalli.service :as service]))\n\n(service/-main)\n</code></pre>"},{"location":"clojure-cli/repl-startup/#repl-help-menu","title":"REPL Help menu","text":"<p>Printing a menu of functions provided by the custom user namespace helps with the usability of a project.</p> <p>Define a <code>help</code> function that prints out commands with a breif explination of their purpose.</p> <p>Add a <code>(help)</code> expression to call the help function on REPL startup, displaying the help menu. </p> <p>REPL Help menu</p> <pre><code>;; ---------------------------------------------------------\n;; Help\n\n(println \"---------------------------------------------------------\")\n(println \"Loading custom user namespace tools...\")\n(println \"---------------------------------------------------------\")\n\n(defn help\n  []\n  (println \"---------------------------------------------------------\")\n  (println \"System components:\")\n  (println \"(start)                        ; starts all components in system config\")\n  (println \"(restart)                      ; read system config, reloads changed namespaces &amp; restarts system\")\n  (println \"(stop)                         ; shutdown all components in the system\")\n  ;; (println \"(system)                       ; show configuration of the running system\")\n  ;; (println \"(config)                       ; show system configuration\")\n  (println)\n  (println \"Hotload libraries:             ; Clojure 1.12.x\")\n  (println \"(add-lib 'library-name)\")\n  (println \"(add-libs '{domain/library-name {:mvn/version \\\"v1.2.3\\\"}})\")\n  (println \"(sync-deps)                    ; load dependencies from deps.edn\")\n  (println \"- deps-* lsp snippets for adding library\")\n  (println)\n  (println)\n  (println \"Portal Inspector:\")\n  (println \"- portal started by default, listening to all evaluations\")\n  (println \"(inspect/clear)                ; clear all values in portal\")\n  (println \"(remove-tap #'inspect/submit)  ; stop sending to portal\")\n  (println \"(inspect/close)                ; close portal\")\n  (println)\n  (println \"(help)                         ; print help text\")\n  (println \"---------------------------------------------------------\"))\n\n(help)\n\n;; End of Help\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#log-publisher","title":"Log publisher","text":"<p>mulog is a very effective event log tool that also provides a range of log publishers.  A custom user namespace can be used to start mulog log publishers to directly support the development workflow</p> <ul> <li>pretty print console output for easier to read event messages</li> <li>custom tap-publisher to send all log message to a <code>tap&gt;</code> source, e.g. Portal data inspector</li> </ul> <p>Mulog configuration and publishers</p> <p>Require the mulog namespaces.</p> <p>Set the global context for all mulog events, setting common key/value pairs that appear in every event created after the global context was evaluated.</p> <p>Define a custom publisher to send all mulog events to the registered tap&gt; sources, e.g. Portal data inspector.</p> dev/mulog_events.clj<pre><code>;; ---------------------------------------------------------\n;; Mulog Global Context and Custom Publisher\n;;\n;; - set event log global context\n;; - tap publisher for use with Portal and other tap sources\n;; - publish all mulog events to Portal tap source\n;; ---------------------------------------------------------\n\n(ns mulog-events\n  (:require\n   [com.brunobonacci.mulog        :as mulog]\n   [com.brunobonacci.mulog.buffer :as mulog-buffer]))\n\n;; ---------------------------------------------------------\n;; Set event global context\n;; - information added to every event for REPL workflow\n(mulog/set-global-context! {:app-name \"todo-basic Service\",\n                            :version \"0.1.0\", :env \"dev\"})\n;; ---------------------------------------------------------\n\n;; ---------------------------------------------------------\n;; Mulog event publishing\n\n(deftype TapPublisher\n         [buffer transform]\n  com.brunobonacci.mulog.publisher.PPublisher\n  (agent-buffer [_] buffer)\n  (publish-delay [_] 200)\n  (publish [_ buffer]\n    (doseq [item (transform (map second (mulog-buffer/items buffer)))]\n      (tap&gt; item))\n    (mulog-buffer/clear buffer)))\n\n#_{:clj-kondo/ignore [:unused-private-var]}\n(defn ^:private tap-events\n  [{:keys [transform] :as _config}]\n  (TapPublisher. (mulog-buffer/agent-buffer 10000) (or transform identity)))\n\n(def tap-publisher\n  \"Start mulog custom tap publisher to send all events to Portal\n  and other tap sources\n  `mulog-tap-publisher` to stop publisher\"\n  (mulog/start-publisher!\n   {:type :custom, :fqn-function \"mulog-events/tap-events\"}))\n\n#_{:clj-kondo/ignore [:unused-public-var]}\n(defn stop\n  \"Stop mulog tap publisher to ensure multiple publishers are not started\n Recommended before using `(restart)` or evaluating the `user` namespace\"\n  []\n  tap-publisher)\n\n;; Example mulog event message\n;; (mulog/log ::dev-user-ns :message \"Example event message\" :ns (ns-publics *ns*))\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#reload-namespaces","title":"Reload Namespaces","text":"<p>The REPL state can become 'stale' and contain vars (data and function names) that are no longer part of the source code, especially after a code refactor.</p> <p>Rather than restart the repl, clojure.tools.namespace.repl provides functions that can clean the REPL state and reload changed namespaces from source code.</p> <p>Clojure Namespace Tools - reload</p> <p>Require the <code>clojure.tools.namespace.repl</code> namespace to access the <code>refresh</code> and <code>set-refresh-dirs</code> functions to support reloading of source code into a clean REPL state.</p> dev/user.clj<pre><code>(ns user\n  \"Tools for REPL Driven Development\"\n  (:require\n   [clojure.tools.namespace.repl :refer [set-refresh-dirs]]))\n</code></pre> <p>Use the <code>set-refresh-dirs</code> function to define directories to reload when calling <code>refresh</code>, effectively excluding <code>dev</code> and other directories by not including their names as arguments.</p> dev/user.clj<pre><code>;; ---------------------------------------------------------\n;; Avoid reloading `dev` code\n;; - code in `dev` directory should be evaluated if changed to reload into repl\n(println\n \"Set REPL refresh directories to \"\n (set-refresh-dirs \"src\" \"resources\"))\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/repl-startup/#hotload-libraries","title":"Hotload libraries","text":"<p>Hotload is a way to add libraries to a running REPL process which were not include as a dependency during REPL startup.</p> Hotload libraries is SNAPSHOT feature - this guide will change when Clojure 1.12 is released <p>Functions to hotload libraries are part of the Clojure 1.12 development releases and an official feature as of the stable 1.12 release.</p> <p>For Clojure 1.11 and similar functions are available in the add-libs3 branch of the now deprecated <code>clojure.tools.deps.alpha</code> library.  </p> <p>clojure/tools.deps is the official library for all released functions from the alpha library</p> <p>This guide will be significantly rewritten once Clojure 1.12 is released.</p>  Practicalli Clojure CLI ConfigManual <p><code>:repl/reloaded</code>  and <code>dev/reloaded</code> aliases in  Practicalli Clojure CLI Config provide the <code>add-libs</code> function.</p> <p>Edit the project <code>deps.edn</code> configuration and add an <code>:lib/hotload</code> alias for the <code>clojure.tools.deps.alpha.repl</code> library.  Or add an alias to the user level configuration for use with any Clojure CLI project.</p> <p>The <code>add-libs</code> code is on a separate add-libs3 branch, so requires the SHA from the head of add-libs3 branch</p> <pre><code>  :lib/hotload\n  {:extra-deps {org.clojure/tools.deps.alpha\n               {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> <p>Alias example from  Practicalli Clojure CLI Config</p> <p>Start a REPL session using Clojure CLI with <code>:repl/reloaded</code>, <code>dev/reloaded</code> or <code>:lib/hotload</code> aliases</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Require and refer add-libs function</p> <p>Require the <code>clojure.tools.deps.alpha</code> library and refer the <code>add-libs</code> function.  The <code>add-libs</code> function can then be called without having to use an alias or the fully qualified name. <pre><code>(require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n</code></pre></p> <p>Hotload one or more libraries into the REPL using the <code>add-lib</code> function, including the fully qualified name of the library and version string.</p> <p>Hotload the hiccup library</p> <p>The hiccup library converts clojure structures into html, where vectors represent the scope of keywords that represent html tags. Load the hiccup library using add-libs <pre><code>(add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n</code></pre></p> <p>Require the hiccup library so its functions are accessible from the current namespace in the REPL. <pre><code>(require '[hiccup.core :as hiccup])\n</code></pre> Enter an expression using the <code>hiccup/html</code> function to convert a clojure data structure to html. <pre><code>(hiccup/html [:div {:class \"right-aligned\"}])\n</code></pre></p>"},{"location":"clojure-cli/repl-startup/#system-components","title":"System Components","text":"<p>Clojure has several library to manage the life-cycle of components that make up the Clojure system, especially those components with state. The order in which components are started and stopped can be defined to keep the system functioning correctly.</p> <p>Components can include an http server, routing, persistence, logging publisher, etc.</p> <p>Example system component management libraries included</p> <ul> <li>mount - manage system state in an atom</li> <li>integrant and Integrant REPL - data definition of system and init &amp; halt defmethod interface</li> <li>donut system</li> <li>component</li> </ul> <p>Require system namespace in user ns expression</p> <p>Require the system namespace and use <code>start</code>, <code>restart</code> and <code>stop</code> functions to manage the components in the system dev/user.clj<pre><code>(ns user\n  (:require [system]))\n\n(comment\n  (system/start)\n  (system/restart)\n  (system/stop)\n  )\n</code></pre></p> <p>Define code in the <code>dev/system.clj</code> file which controls the component life-cycle services library for the project.</p> <p>Create a <code>dev/system.clj</code> to manage the components, optionally using one of the system component management libraries.</p>"},{"location":"clojure-cli/repl-startup/#life-cycle-functions","title":"life-cycle functions","text":"<p>Start, stop and restart the components that a system is composed of, e.g. app server, database pool, log publisher, message queue, etc.</p> Atom restartMountIntegrant REPLDonut SystemComponent <p>Clojure web services run ontop of an HTTP server, e.g. http-kit, Jetty.</p> <p>A Clojure aton can be used to hold a reference to the HTTP server, allowing commands to stop that server.</p> <p>Use <code>clojure.tools.namespace.repl/refresh</code> when restarting the server (in between <code>stop</code> and <code>start</code>) to remove stale information in the REPL state.</p> <p>Restart an HTTP server for Clojure Web Service &amp; Refresh namespaces</p> dev/system_repl.clj<pre><code>;; ---------------------------------------------------------\n;; System REPL - Atom Restart \n;;\n;; Tools for REPl workflow with Aton reference to HTTP server \n;; https://practical.li/clojure-web-services/app-servers/simple-restart/\n;; ---------------------------------------------------------\n\n(ns system-repl\n  (:require \n    [clojure.tools.namespace.repl :refer [refresh]]\n    [practicalli.todo-basic.service :as service]))\n\n;; ---------------------------------------------------------\n;; HTTP Server State\n\n(defonce http-server-instance \n  (atom nil))  ; (1)! \n;; ---------------------------------------------------------\n\n;; ---------------------------------------------------------\n;; REPL workflow commands\n\n(defn stop\n  \"Gracefully shutdown the server, waiting 100ms.\n   Check if an http server isntance exists and \n   send a `:timeout` key and time in milliseconds to shutdown the server.\n   Reset the atom to nil to indicate no http server is running.\"\n  []\n  (when-not (nil? @http-server-instance)\n    (@http-server-instance :timeout 100) ; (2)!\n    (reset! http-server-instance nil)  ; (3)!\n    (println \"INFO: HTTP server shutting down...\")))\n\n(defn start\n  \"Start the application server and run the application,\n   saving a reference to the https server in the atom.\"\n  [&amp; port]\n  (let [port (Integer/parseInt\n              (or (first port)\n                  (System/getenv \"PORT\")\n                  \"8080\"))]\n    (println \"INFO: Starting server on port:\" port)\n\n    (reset! http-server-instance\n            (service/http-server-start port)))) ; (4)!\n\n\n(defn restart\n  \"Stop the http server, refresh changed namespace and start the http server again\"\n  []\n  (stop)\n  (refresh)  ; (5)! \n  (start))\n;; ---------------------------------------------------------\n</code></pre> <ol> <li> <p>A Clojure Aton holds a reference to the http server instance</p> </li> <li> <p>Shut down http server instance without stopping the Clojure REPL</p> </li> <li> <p>Reset the value in the atom to mil, indicating that no http server instance is running</p> </li> <li> <p>Reset the value in the atom to a reference for the running http server.  The reference is returned when starting the http server.</p> </li> <li> <p>Refresh the REPL state and reload changed namespaces from source code using <code>clojure.tools.namespace.repl/refresh</code></p> </li> </ol> <p>Define a <code>dev.clj</code> file with <code>go</code>, <code>stop</code> and <code>restart</code> functions that manage the life-cycle of mount components.  A <code>start</code> function contains the list of components with optional state.</p> <p>Require the mount namespace and the main namespace for the project, which should contain all the code to start and stop services.</p> dev/user.clj<pre><code>(ns user\n  :require [mount.core :refer [defstate]]\n           [practicalli.app.main])\n</code></pre> <p>Define a start function to start all services</p> dev/user.clj<pre><code>(defn start []\n  (with-logging-status)\n  (mount/start #'practicalli.app.conf/environment\n               #'practicalli.app.db/connection\n               #'practicalli.app.www/business-app\n               #'practicalli.app.service/nrepl))\n</code></pre> <p>The <code>go</code> function calls <code>start</code> and marks all components as ready.</p> dev/user.clj<pre><code>(defn go\n  \"Start all states defined by defstate\"\n  []\n  (start)\n  :ready)\n</code></pre> <p>The <code>stop</code> function stops all components, removing all non-persistent state.</p> <pre><code>(defn stop [] (mount/stop))\n</code></pre> <p>The reset function that calls <code>stop</code>, refreshes the namespaces so that stale definitions are removed and starts all components (loading in any new code).</p> dev/user.clj<pre><code>(defn reset\n  \"Stop all states defined by defstate.\n  Reload modified source files and restart all states\"\n  []\n  (stop)\n  (namespace/refresh :after 'dev/go))\n</code></pre> <p> Example dev.clj file for mount</p> <p>Use <code>dev</code> namespace during development</p> <p>Require <code>practicalli.app.dev</code> namespace rather than main, to start components in a development environment.</p> <p> Integrant REPL - Practicalli Clojure Web Services</p> <p>User manager - Integrant</p> <p>donut.system is a dependency injection library for Clojure and ClojureScript using system and component abstractions to organise and manage startup &amp; shutdown behaviour.</p> <p>Basic usage guide shows how to define a donut.system</p> <p><p> </p></p> <p>seancorfield/usermanager-example is an example project that uses Component for lifecycle management</p>"},{"location":"clojure-cli/repl-startup/#reference","title":"Reference","text":"<ul> <li>Mount project on GitHub</li> <li>Mount - collection of Clojure/Script mount apps</li> <li>donut.system</li> <li>Component</li> <li>A tutorial to Stuart Sierra's Component</li> <li>Refactoring to Components - Walmart Labs Lacinia</li> <li>Integrant</li> <li>Compojure and Integrant</li> <li>Build a Clojure web app using Duct - CircleCI</li> <li>Reloading Woes - Lambda island</li> </ul>"},{"location":"clojure-cli/projects/","title":"Clojure projects","text":"<p>Clojure CLI projects use a <code>deps.edn</code> file to specifies source paths and libraries required for the project to run.   </p> <p>alias are defined in the  <code>deps.edn</code> file to support development tasks, providing additional libraries, paths and tools. </p> <p>Generate a project from a template</p> <p>Create a project from a template for a consistent project structure and include commonly used libraries.</p> <p>Practicalli Project Templates create production grade projects providing a detailed starting point with configuration files for building and deploying the project.</p>"},{"location":"clojure-cli/projects/#create-minimal-project","title":"Create minimal project","text":"<p>Create a <code>deps.edn</code> file containing <code>{}</code> in the root of a directory for a minimal configuration.</p> <p>Create a <code>src</code> directory as the root of the source code, and <code>test</code> directory to contain unit test code.</p> Linux command to create a minimal clojure project <p>Run these Linux commands in the root of a directory to create a minimal Clojure project structure. <pre><code>touch deps.edn &amp;&amp; echo '{}' &gt; deps.edn &amp;&amp; mkdir src test\n</code></pre></p> <p>The project can now be run with a REPL via a terminal UI or Clojure aware Editor.</p> Migrate project to Clojure CLI <p>Guide to Migrating a project to Clojure CLI</p>"},{"location":"clojure-cli/projects/#project-structure","title":"Project Structure","text":"<p>The essence of most Clojure CLI projects contains the following files and directories.</p> path purpose deps.edn core project configuration, paths, dependencies and aliases build.clj build specific configuration, create jars and uberjars src root directory of Clojure source files test root directory for Clojure test source files README.md Description of the project and how to develop / maintain it CHANGELOG.md Meaningful history of changes to the project organised by release .git Local git repository and configuration .gitignore Git ignore patterns for the project <p>Example deps.edn configuration file</p> <pre><code>{:paths\n [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure    {:mvn/version \"1.11.1\"}}\n  http-kit/http-kit      {:mvn/version \"2.6.0\"}  \n  metosin/reitit         {:mvn/version \"0.5.13\"}\n  com.brunobonacci/mulog {:mvn/version \"0.9.0\"}\n\n :aliases\n {;; Clojure.main execution of application\n  :run/service\n  {:main-opts [\"-m\" \"practicalli.donuts.service\"]}\n\n  ;; Clojure.exec execution of specified function\n  :run/greet\n  {:exec-fn   practicalli.donuts.service/greet\n   :exec-args {:name \"Clojure\"}}\n\n  ;; Add libraries and paths to support additional test tools\n  :test/env\n  {}\n\n  ;; Test runner - local and CI\n  ;; call with :watch? true to start file watcher and re-run tests on saved changes\n  :test/run\n  {:extra-paths [\"test\"]\n   :extra-deps  {lambdaisland/kaocha {:mvn/version \"1.85.1342\"}}\n   :main-opts   [\"-m\" \"kaocha.runner\"]\n   :exec-fn     kaocha.runner/exec-fn\n   :exec-args   {:randomize? false\n                 :fail-fast? true}}\n\n  ;; tools.build `build.clj` built script\n  :build\n  {:replace-paths [\".\"]\n   :replace-deps  {io.github.clojure/tools.build\n                   {:git/tag \"v0.9.4\" :git/sha \"76b78fe\"}}\n   :ns-default    build}}}\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/","title":"Add libraries to a project","text":"<p>The project <code>deps.edn</code> file is used to add specific versions of libraries to a project.</p> <p>The <code>:deps</code> top-level key defines libraries that are always included, e.g when starting the REPL or packaging a project in an Uberjar.</p> <p>Aliases are defined to include libraries only when the alias name is included, e.g. <code>:dev/reloaded</code> alias includes several libraries only relevant during development of a Clojure project.</p> <p>There are thousands of community Clojure and ClojureScript libraries available via clojars.org and Maven Central.</p> <p><code>:deps</code> top level key contains a hash-map of dependencies, each dependency of the form <code>domain/name {:mvn/version \"version-number\"}</code></p> Project deps.edn<pre><code>{:deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}\n  hiccup/hiccup       {:mvn/version \"2.0.0-alpha2\"}}}\n</code></pre> Finding libraries <p>Search for community libraries via the Clojars.org website or visit the Clojure Toolbox to browse some of the community libraries available</p> <p><code>clojure -M:search/libraries pattern</code> where pattern is the name of the library to search for.  Copy the relevant results into the project <code>deps.edn</code> file.</p> <p><code>clojure -M:search/libraries --format:merge pattern</code> will automatically add the library into the <code>deps.edn</code> file.</p> <p><code>clojure -X:deps find-versions :lib fully.qualified/library-name :n 5</code> returns the last 5 versions of the given library.</p>"},{"location":"clojure-cli/projects/add-libraries/#alias-libraries","title":"Alias libraries","text":"<p><code>:aliases</code> top-level key contains a hash-map of alias definitions.</p> <p>Each alias has a unique name with <code>:aliases</code> and is represented by a Clojure keyword associated with a Clojure hash-map, <code>{}</code></p> <p><code>:extra-deps</code> keyword is associated with hash-map that contains one or more fully qualified library names and the version of the library to use.  The version of the library is defined with the maven form <code>{:mvn/version \"0.4.2\"}</code> or Git form <code>{:git/url \"https://github.com/clojure/tools.deps.alpha\" :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}</code></p> <p>The following example can be added to a project <code>deps.edn</code>, within the <code>:aliases {}</code> form.</p> deps.edn alias definition with maven and git versions<pre><code>:dev/reloaded\n{:extra-deps {djblue/portal {:mvn/version \"0.34.2\"}\n              lambdaisland/kaocha {:mvn/version \"1.71.1119\"}\n              org.clojure/test.check {:mvn/version \"1.1.1\"}\n              org.clojure/tools.namespace {:mvn/version \"1.3.0\"}\n              org.clojure/tools.deps.alpha {:git/url \"https://github.com/clojure/tools.deps.alpha\"\n                                            :git/sha \"e4fb92eef724fa39e29b39cc2b1a850567d490dd\"}}}\n</code></pre> <p>When the alias is included in the command to start the REPL, the libraries are placed on the class path and can be required for use.</p> <pre><code>clojure -M:dev/reloaded:repl/rebel\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/#hotload-libraries","title":"Hotload libraries","text":"<p><code>add-libs</code> is a function to load one or more libraries into a running REPL, negating the need to restart the REPL process.</p> <p>Start a REPL process with <code>clojure -M:repl/reloaded</code> to include the add-libs librar. Alternatively, include <code>:dev/reloaded</code> or <code>:lib/hotload</code> alias with any Clojure command to start a REPL.</p> <p>Hotload Libraries explained</p> <p>REPL Reloaded - Hotload Libraries details all the options for including the clojure.tools.deps.alpha library that contains the <code>add-libs</code> function</p> <p>Use a rich comment block or a <code>dev/user.clj</code> file to require the <code>clojure.tools.deps.alpha.repl</code> namespace and write <code>add-libs</code> expressions to hot-load libraries.</p> <p>A rich comment block ensures <code>add-libs</code> code is only evaluated manually by a developer.</p> <pre><code>(comment\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n)\n</code></pre> rich-comment-hotload Clojure LSP snippet <p>Snippets provided by Clojure LSP include <code>rich-comment-hotload</code>, to add a rich comment block with a require for <code>clojure.tools.deps.alpha</code> and an <code>add-libs</code> expression, making it very quick to add this code.</p> <p><code>deps-maven</code> and <code>deps-git</code> snippets help ensure the correct syntax is used for the <code>add-libs</code> expression for each library dependency to be added.</p> <p>Practicalli Clojure LSP Config contains a wide range of snippets</p>"},{"location":"clojure-cli/projects/add-libraries/#hotload-example","title":"Hotload Example","text":"<p>Create a web server from scratch, serving pages generated from hiccup, with all libraries hot-loaded as the code is being written.  Demonstrates that it is possible to write an application when only starting the REPL once.</p> Web server from scratch <pre><code>(comment\n  ;; run REPL with :lib/hotload alias\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n\n  ;; hotload the libraries required for the server\n  (add-libs\n    '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n  ;; =&gt; (http-kit/http-kit)\n\n\n  ;; Require the namespace from the http-kit library\n  (require '[org.httpkit.server :as app-server])\n\n   ;; Define a handler for http requests\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server with the handler\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  ;; Create a page template\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ;; Visit http://localhost:8888/ and refresh the page to see the new welcome-page\n  )\n</code></pre>"},{"location":"clojure-cli/projects/add-libraries/#excluding-dependencies","title":"Excluding dependencies","text":"<p>Adding several libraries as dependencies to a project may cause conflicts. The <code>:exclusions</code>  key will prevent libraries within a library dependency from being included in the project</p> <p>For example, library-a and library-b both have a dependency on library-c, as defined in the project configuration for library-a and library-b.  When including library-a and library-b in the project as dependencies, there could be a conflict if the both libraries use a different version of library-c.  Adding an exclude to library-a or library-b will stop library-c being included twice.</p> <p>A Library that is self-contained and does not itself include any dependencies on any other libraries is unlikely to cause conflicts.  Using these self-contained libraries simplifies the overall application design.</p> <pre><code>{:deps {:org.clojure/clojure {:mvn/version \"1.10.2\"}\n        :cheshire/cheshire  {:mvn/version \"5.10.0\"\n            :exclusions \"com.fasterxml.jackson.core/jackson-core\"}}}\n</code></pre>"},{"location":"clojure-cli/projects/hotload-in-project/","title":"Hotload libraries in Clojure Projects","text":"<p>When starting a REPL process the dependencies listed in the project <code>deps.edn</code> file are added to the class path.  To add further dependencies the REPL has to be  restarted to include new libraries added to the <code>deps.edn</code> file.</p> <p></p> <p>Practicalli REPL Reloaded workflow allows new dependencies to be added to a running REPL process, negating the need to restart the REPL process which would loose the current REPL state.</p>"},{"location":"clojure-cli/projects/hotload-in-project/#hotload-repl","title":"Hotload REPL","text":"<p>Start a REPL with an alias that includes the <code>add-libs</code> library.</p> Terminal REPLClojure Editor <p>Start a terminal  REPL with the <code>:repl/reloaded</code> alias and connect</p> <p><pre><code>clojure -M:repl/reloaded\n</code></pre> Connect to the REPL process from a Clojure editor for an enhanced development experience.</p> <p>Run a Clojure REPL from the editor (jack-in command) configured with the <code>:dev/reloaded</code> alias or <code>:lib/hotload</code> alias in an Editor jack-in command or other REPL startup command.</p> <p>Alternatively, run a Terminal REPL and connect the editor to that REPL process (connect command)</p> <p>Practicalli REPL Reloaded Configuration</p>"},{"location":"clojure-cli/projects/hotload-in-project/#rich-comment-block","title":"Rich Comment Block","text":"<p>Use a rich comment block or a <code>dev/user.clj</code> file to require the <code>clojure.tools.deps.alpha.repl</code> namespace and write <code>add-libs</code> expressions to hot-load libraries.</p> <p>A rich comment block ensures <code>add-libs</code> code is only evaluated manually by a developer.</p> <pre><code>(comment\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n  (add-libs '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n)\n</code></pre> Rich-comment-hotload <p>Practicalli Clojure LSP Config includes the <code>rich-comment-hotload</code> snippet which adds a rich comment block with a require for <code>clojure.tools.deps.alpha</code> and an <code>add-libs</code> expression, making it very quick to add this code.</p> <p><code>deps-maven</code> and <code>deps-git</code> snippets help ensure the correct syntax is used for the <code>add-libs</code> expression for each library dependency to be added.</p>"},{"location":"clojure-cli/projects/hotload-in-project/#hotload-example","title":"Hotload Example","text":"<p>Create a web server from scratch, serving pages generated from hiccup, with all libraries hot-loaded as the code is being written.  Demonstrates that it is possible to write an application when only starting the REPL once.</p> <pre><code>(comment\n  ;; run REPL with :lib/hotload alias\n  (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n\n  ;; hotload the libraries required for the server\n  (add-libs\n    '{http-kit/http-kit {:mvn/version \"2.5.1\"}})\n  ;; =&gt; (http-kit/http-kit)\n\n\n  ;; Require the namespace from the http-kit library\n  (require '[org.httpkit.server :as app-server])\n\n   ;; Define a handler for http requests\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    \"Welcome to the world of Clojure CLI hotloading\"\n     :headers {}})\n\n  ;; Start the application server with the handler\n  (app-server/run-server #'welcome-page {:port (or (System/getenv \"PORT\") 8888)})\n\n  ;; Visit http://localhost:8888/ to see the welcome-page\n\n  ;; Hotload Hiccup to generate html for the welcome page\n  (add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n\n  (require '[hiccup.core :as hiccup])\n  (require '[hiccup.page :as hiccup-page])\n\n  ;; Create a page template\n  (defn page-template [content]\n    (hiccup-page/html5\n      {:lang \"en\"}\n      [:head (hiccup-page/include-css \"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\")]\n      [:body\n       [:section {:class \"hero is-info\"}\n        [:div {:class \"hero-body\"}\n         [:div {:class \"container\"}\n          [:h1 {:class \"title\"} (:title content) ]\n          [:p {:class \"subtitle\"} (:sub-title content)]]]]]))\n\n  ;; Check the page template returns HTML\n  (page-template {:title     \"Hotload Libraries in the REPL\"\n                  :sub-title \"REPL driven development enables experimentation with designs\"})\n\n\n  ;; redefine the welcome page to call the page template\n  (defn welcome-page\n    [request]\n    {:status  200\n     :body    (page-template {:title     \"Hotload Libraries in the REPL\"\n                              :sub-title \"REPL driven development enables experimentation with designs\"})\n     :headers {}})\n\n  ;; Visit http://localhost:8888/ and refresh the page to see the new welcome-page\n  )\n</code></pre> Using add-libs with project deps.edn <p>A project <code>deps.edn</code> file can also be used to hotload libraries with <code>add-lib</code>.  This has the advantage that newly added libraries become part of the normal project dependency configuration.</p> <p>Add a namespace definition to the <code>deps.edn</code> file to help editors understand the <code>deps.edn</code> file is being used for code.  Use the <code>#_</code> comment reader macro with the namespace definition to only evaluate this code manually as a developer.</p> <p>Add the <code>add-libs</code> expression after the <code>:deps</code> key so that it is easy to slurp in the existing and new dependencies as a single hash-map.  Use the comment reader macro <code>#_</code> to only evaluate this code manually.</p> <p>To hotload, remove the <code>#_</code> temporarily and slurp in the hash-map of dependencies, placing a <code>'</code> at the start of the hash-map.  Add the name and version of libraries to hotload in the hash-map.  Evaluate the <code>add-libs</code> expression which should return a list of new namespaces added.</p> <p>Once hotload has finished, barf the hash-maps of dependencies from the <code>add-libs</code> expression, removing the <code>'</code>.  Add the <code>#_</code> to the <code>add-libs</code> expression and save the file.</p> <p>The hotloaded libraries are now available by requiring their namespaces.  If the REPL is restarted, the new dependencies will be included in the Classpath as they are now part of the project configuration.</p> <pre><code>;; ---------------------------------------\n;; Project Configuration with  Hotload\n;; ---------------------------------------\n\n;; Hotload requires\n#_(ns deps.edn\n    (:require [clojure.tools.deps.alpha.repl :refer [add-libs]]))\n\n;; Project configuration\n{:paths\n [\"src\" \"resources\"]\n\n :deps\n #_ (add-libs)\n {org.clojure/clojure {:mvn/version \"1.10.1\"}\n  http-kit/http-kit   {:mvn/version \"2.5.1\"}\n  hiccup/hiccup       {:mvn/version \"2.0.0-alpha2\"}}\n\n :aliases {}\n</code></pre>"},{"location":"clojure-cli/projects/hotload-in-project/#live-coding-video","title":"Live Coding video","text":"<p>See the REPL driven development video by Sean Corfield for this technique.</p> <p> </p> <p>Jump to 23 minutes into the video to see this form of hotload in action.</p>"},{"location":"clojure-cli/projects/migrate-project/","title":"Migrating Project To Clojure CLI","text":"<p>Migrating an existing project to Clojure CLI can be as simple as the addition of a <code>deps.edn</code> configuration file.</p> <p>Leiningen plugins that change code</p> <p>A few Leiningen plugins inject code into a project to make it work.  For example, lein-ring injects Clojure code into the project to run an application server.  These type of plugins may require updates to the Clojure code in the project.</p>"},{"location":"clojure-cli/projects/migrate-project/#minimal-approach","title":"Minimal approach","text":"<p>Create a <code>deps.edn</code> file in the root of the project directory, containing an empty hash-map, <code>{}</code></p> <p>The Clojure version will be taken from the Clojure CLI tools install configuration.</p> <p>This configuration is enough to run a terminal REPL UI for the project, although requiring namespaces from the project may require libraries to be added as dependencies first.</p>"},{"location":"clojure-cli/projects/migrate-project/#adding-dependencies","title":"Adding dependencies","text":"<p>All Clojure projects require the <code>org.clojure/clojure</code> library and a specific version is defined in the configuration that comes with the Clojure CLI install.</p> <p>Use the <code>:deps</code> key in <code>deps.edn</code> to specify a version of the <code>org.clojure/clojure</code> library, along with any dependencies required for the Clojure code to run.</p> <pre><code>{:deps\n {org.clojure/clojure {:mvn/version \"1.11.1\"}\n  integrant/integrant {:mvn/version \"0.8.0\"}}}\n</code></pre> REPL Reloaded - add-libs hotload dependencies <p>Practicalli REPL Reloaded provides the add-libs function that can hotload libraries into the running REPL, without having to restart the REPL process.</p> <p>The hotload approach can also be useful for diagnosing conflicts in dependencies by loading them in stages to narrow down the library causing the conflict.</p>"},{"location":"clojure-cli/projects/migrate-project/#adding-paths","title":"Adding paths","text":"<p>It is advisable to specify the directory paths to define the location of the source code in the project, especially when running the project in other environments such as a continuous integration server.</p> <p>Edit the <code>deps.edn</code> file in the root of the project directory and add source directory and if relevant the resources directory.</p> <pre><code>{:paths\n   [\"src\" `resource`]}\n</code></pre>"},{"location":"clojure-cli/projects/migrate-project/#add-test-runner","title":"Add test runner","text":"<p>Tests can be run locally using the <code>:test/run</code> or <code>:test/watch</code> aliases from the  Practicalli Clojure CLI Config.</p> Continuous Integration Support <p>A Continuous Integration server requires an alias in the project <code>deps.edn</code> file to define a test runner.</p> <p>A selection of test runners are provided via aliases defined in  Practicalli Clojure CLI Config.  Copy a test runner alias to the project <code>deps.edn</code> file.</p>"},{"location":"clojure-cli/projects/migrate-project/#deployment","title":"Deployment","text":"<p>A Continuous Delivery pipeline will require an alias in the project <code>deps.edn</code> file to define how to build a jar or uberjar to package the Clojure project.</p> <p>Project Package section details how to use <code>tools.build</code> to create jar and uberjar archives of the project for deployment.</p>"},{"location":"clojure-cli/projects/migrate-project/#migration-tools","title":"Migration Tools","text":"<p>Several tools exist to support migration from Leiningen projects to Clojure CLI projects.  Results will be dependant on how complex the Leiningen project configuration is.</p> <ul> <li>lein-to-deps - create a <code>deps.edn</code> configuration from a <code>project.clj</code> configuration</li> <li>lein-tools-deps - share Clojure CLI dependencies with Leiningen project configuration.</li> </ul>"},{"location":"clojure-cli/projects/namespace/","title":"Namespaces","text":"<p>Using namespaces  makes code easier to work with by provide levels of abstraction that convey the overall design of the project.  Clearly organized namespaces support a simple design approach for a project and make it easier to maintain.</p> <p>A namespace is a logical separation of code, usually along features of the projects. Think of all namespaces as creating an API's within the project that communicate the architecture of the system.</p> <p></p>"},{"location":"clojure-cli/projects/namespace/#controlling-scope","title":"Controlling scope","text":"<p>Logically related data structures and functions are defined within a namespace, limiting their default scope to that namespace.</p> <p>Namespaces should limit their interdependence on each other (limited number of required namespaces) to avoid a highly coupled design.</p> <p>Within a namespace a var (<code>def</code>, <code>defn</code>) can be called by its short-form name.  Outside of the namespace, a fully qualified name must be used, or required via an alias or directly referred.</p> <p>Vars can be marked as private, <code>def ^private name</code>, so they can be accessed only by functions in their own namespace (athough there are ways to by-pass that scope restiction).</p>"},{"location":"clojure-cli/projects/namespace/#including-another-namespace","title":"Including another namespace","text":"<p><code>(ns namespace.name (:require [domain/filename :as purpose]))</code> is used to enable access to the functions &amp; named data structures in another namespace than the current one.  The included namespace is given an alias so its clear which code comes from that namespace.</p> <p>Practicalli recommends using a meaningful alias that defines the purpose of the library you are including.  This helps with the understanding and maintainability of the code, especially if you wish to refactor and replace the included library with an alternative.  An alias name should be meaningful and you should avoid single character and cryptic aliases.</p> <pre><code>(ns my-namespace.core\n  :require [clojure.java.io :as java-io])\n\n(defn read-the-file [filename]\n  (line-seq (java-io/reader filename)))\n\n(read-the-file \"project.clj\")\n</code></pre> <p>Trying out a namespace</p> <p><code>(require '[domain/filename])</code> can be used within you code if testing that namespace functions to see if they are useful to the project.  Using a live linter such as clj-kondo, part of Clojure LSP, will highlight missing namespaces.</p>"},{"location":"clojure-cli/projects/namespace/#including-specific-parts-of-a-namespace","title":"Including specific parts of a namespace","text":"<p><code>:refer</code> in the <code>require</code> expression includes one or more specific vars directly in the current namespace, as if it had been defined there. Referring a var means it no longer requires a namespace qualifier.</p> <p>Use <code>:refer</code> when the library being required the predominant focus of that namespace. A good example is <code>clojure.test</code> which is included to specifically write unit tests.</p> <pre><code>(ns practicalli.gameboard.handler-test\n  :require\n    [clojure.test :refer [deftest is testing]]\n    [practicalli.gameboard.handler :as handler])\n\n(deftest highscore-test\n  (testing \"A description of the test\"\n    (is (true? (handler/public-function 42)))))\n</code></pre> <p>(deftest public-function-in-namespace-test   (testing \"A description of the test\"     (is (= 1 (public-function arg)))     (is (predicate-function? arg))))</p> Rarely used options - include exclude rename vars <p>These other options on required functions are rarely used in practice.  They tend to cause more issues than they solve, so use with care.</p> <p><code>:exclude</code> will prevent a var from being used from a required namespace.</p> <p><code>:only</code> will include only that var from the required namespace.</p> <p><code>:rename</code> changes the name of the original function, if there conflicts</p>"},{"location":"clojure-cli/projects/namespace/#adding-multiple-namespaces","title":"Adding multiple namespaces","text":"<p>The idiom in Clojure is to include multiple namespaces with just one <code>:require</code> statement</p> <p>Here is an example namespace expression with multiple require statements from the duct web framework template</p> <pre><code>(ns duct-test.main\n  (:require [clojure.java.io :as io]\n            [com.stuartsierra.component :as component]\n            [duct.middleware.errors :refer [wrap-hide-errors]]\n            [meta-merge.core :refer [meta-merge]]\n            [duct-test.config :as config]\n            [duct-test.system :refer [new-system]]))\n</code></pre> <p>Avoid use form - require should be used</p> <p>The <code>use</code> or <code>:use</code> form is not recommended as it pulls in everything the namespace and everything that the included namespace also included.  This can lead to conflicts, especially in larger projects.</p> <p>As Clojure is typically composed of many libraries, its prudent to only include the specific things you need from another namespace.</p>"},{"location":"clojure-cli/projects/namespace/#design-refactor","title":"Design &amp; Refactor","text":"<p>When starting a new project all the code is typically in one namespace, unless you are using a template that creates multiple namespaces with sample code.</p> <p>Practicalli recommends adding comment sections as the code is developed, grouping code by its purpose.  As the namespace grows in size and complexity, these groups can be moved into their own namespaces as necessary.  A code refactor is much simpler as the code is already grouped logically by purpose.</p> Code comment sections <pre><code>;; --------------------------------------------------\n;; State\n\n;; --------------------------------------------------\n\n;; --------------------------------------------------\n;; Helper functions\n\n;; --------------------------------------------------\n\n;; --------------------------------------------------\n;; System / Lifecycle\n\n;; --------------------------------------------------\n</code></pre> <p>Clojure LSP Snippets</p> <p>Practicalli Clojure LSP Config defines snippets to create sections within a Clojure file</p> <p><code>comment-header</code> to describe the overall purpose of the namespace</p> <p><code>comment-section</code> creates a start and end comment line and text comment</p> <p>One pass evaluation</p> <p>A Clojure file is evaluated from top to bottom, so var (<code>def</code>, <code>defn</code>) definitions should come before they are used in the code.</p>"},{"location":"clojure-cli/projects/rich-comments/","title":"Rich Comments","text":"<p>The <code>(comment ,,,)</code> form is commonly used to contain living experimental code, so it is often referred to as a rich comment as its purpose is more than just commenting out code.</p>"},{"location":"clojure-cli/projects/rich-comments/#experimental-design","title":"Experimental design","text":"<p>Whilst iterating through designs, much experimental code can be created which is not (yet) ready to be part of the main namespace.</p> <p>Experimental code can be written in a <code>(comment ,,,)</code> form to keep it separate from more finalised implementations.</p> <p>When a namespace is evaluted, code within the <code>(comment ,,,)</code> form is not automatically loaded.</p> <p>Most editors support evaluation of Clojure code within the <code>(comment ,,,)</code> form, allowing a range of design implementations to be evaluated against each other.</p> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <p>Practicalli Clojure LSP Config - rich-comment-hotload snippet</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n\n  (def data-model {:nested {:hash \"map\" :design \"choice\"}})\n  (def data-model [{:collection \"of\" :hash \"maps\" :design \"choice\"}\n                   {:collection \"of\" :hash \"maps\" :design \"choice\"}])\n\n  (defn value-added-tax []\n    ;; algorithm - initial design)\n\n  (defn value-added-tax []\n    ;; algorithm - alternate design)\n\n  ) ; End of rich comment block\n</code></pre>"},{"location":"clojure-cli/projects/rich-comments/#design-journal","title":"Design Journal","text":"<p>When the problem domain or libraries selected are relatively unknown, a significant amount of learning and experimentation may be required.  This learning can be captured in a separate namespace, often referred to as a design journal.</p> <p>Creating a journal of the decisions made as code is designed makes the project easier to understand and maintain.  Journals avoid the need for long hand-over or painful developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A design journal can be added as a <code>(comment ,,,)</code> section at the bottom of each namespace, or more typically in its own namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Practicalli example journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"clojure-cli/projects/rich-comments/#snippets","title":"Snippets","text":"<p>clojure-lsp contains a number of snippets to create variations of a comment form.</p> <ul> <li><code>rich-comment</code> a basic comment form</li> <li><code>rich-comment-rdd</code> comment form that informs clj-kondo to ignore duplicate function definitions, avoids warnings when testing multiple implementations of the same function</li> <li><code>rich-comment-hotload</code> - comment form with Clojure CLI library hotloading</li> </ul>"},{"location":"clojure-cli/projects/rich-comments/#migrating-design-to-tests","title":"Migrating design to tests","text":"<p>REPL code experiements within rich comment blocks are often a good source of code that can be converted into formal unit tests.</p> <p>Example values used to test functions as they are designed can be useful to create meaningful sets of test data, especially when testing edge conditions.</p>"},{"location":"clojure-cli/projects/rich-comments/#live-examples","title":"Live examples","text":"<p>A rich comment at the end of a namespace can include code that demonstrates how to use the key aspects of the namespace API.</p> <p></p>"},{"location":"clojure-cli/projects/package/","title":"Package with Clojure tools.build","text":"<p>The  Clojure.org tools.build project is used to build jar files to deploy libraries and uberjar files to run deployed projects (e.g. in Docker containers or directly on an Operating System with Java JVM installed).</p> <p>Clojure tools.build is a library to define build related tasks using Clojure code.</p> <p>Practicalli Project Templates includes tools.build configuration</p> <p>Clojure projects created with Practicalli Project Templates include a <code>build.clj</code> configuration to build an uberjar of the project.</p> <p>The <code>make build-jar</code> runs the <code>clojure -T:build jar</code> command to build an uberjar.</p> Java ARchive - jar file <p>A <code>.jar</code> file is a zip archive of the project containing all the files for running a Clojure project.  The archive should contain metatdata files such as Manifest and pom.xml and can contain Clojure sources or compiled class files from the project (or both).</p> <p>An ubjerjar is <code>.jar</code> file that also contains all the project dependencies including Clojure.  The uberjar is a self-contained file that can be easily deployed and requires only a Java run-time (Java Virtual Machine), using the <code>java -jar project-uberjar.jar</code> command, with the option to pass arguments to the Uberjar also.</p> Practicalli Project Build tasksClojure tools.build <p> Practicalli Project templates include a <code>build.clj</code> configuration with <code>jar</code> and <code>uberjar</code> tasks.</p> <p>Create a runnable Clojure archive</p> <pre><code>clojure -T:project/build uberjar\n</code></pre> <p>Create a Clojure library archive</p> <pre><code>clojure -T:project/build jar\n</code></pre> <p>tools.build provides an API for pragmatically defining tasks to build Clojure projects.</p> <p>Create a <code>build.clj</code> configuration with tasks for building a library jar or runable uberjar.</p> <p> Define build.clj configuration for tools.build</p>"},{"location":"clojure-cli/projects/package/tools-build/","title":"Package projects with tools.build","text":"Improved build script examples have been added <p>Please report any issues using the new examples</p> <p> Clojure.org tools.build is a library to define build related tasks using Clojure code.</p> <p>The  tools.build API provides a consistent interface to access the project configuration (project basis) and common tasks that facilitate building and packaging projects.</p> <p>Include a build alias and build script in each project to make use of Clojure tools.build:</p> <ul> <li><code>:build/task</code> alias adding tools.build library to the class path in the project <code>deps.edn</code> file</li> <li><code>build.clj</code> defines a namespace requiring tools.build, a project configuration and functions as build tasks</li> </ul> Practicalli Project Templates include tools.build tasks <p> Practicalli Project templates include a <code>build.clj</code> tasks to generate a library <code>jar</code> or a service <code>uberjar</code>.</p>"},{"location":"clojure-cli/projects/package/tools-build/#define-build-alias","title":"Define build alias","text":"<p>Add an alias to the project <code>deps.edn</code> file which includes the <code>org.clojure/tools.build</code> project.</p> <p>:build/task alias created by Practicalli Project Templates</p> Project deps.edn<pre><code>  ;; tools.build `build.clj` built script\n  :build/task\n  {:replace-paths [\".\"]\n   :replace-deps {io.github.clojure/tools.build\n                  {:git/tag \"v0.9.6\" :git/sha \"8e78bcc\"}}\n   :ns-default build}\n</code></pre> <p>Use Clojure CLI to run any of the tasks defined in the <code>build</code> namespaces.</p> <pre><code>clojure -T:build/task task-name\n</code></pre> tools.build release information <p>Clojure.org tools.build release information shows the current values for <code>git/tag</code> and <code>:git/sha</code></p> Developing code in the build script <p><code>:replace-paths [\".\"]</code> includes the <code>build.clj</code> file on the class path to allow for REPL development of the build tasks</p> <p>Include <code>:build</code> alias in the Clojure command when starting the REPL. <pre><code>clojure -M:build/task:repl/rebel\n</code></pre></p>"},{"location":"clojure-cli/projects/package/tools-build/#build-script","title":"Build Script","text":"<p>Create a <code>build.clj</code> file which defines a namespace requiring tools.build, a project configuration and functions as build tasks</p> <p>An Uberjar file is built to deploy a Clojure service, e.g. in test, staging or production environment.</p> <p>A Jar file is built to published a Clojure library to a Maven repository, e.g. Clojars.org, Maven Central or a private Maven repository.</p>"},{"location":"clojure-cli/projects/package/tools-build/#namespace-definition","title":"Namespace definition","text":"<p>Define the namespace and require the clojure.tools.build.api and any additional libraries.</p> Service UberjarLibrary Jar <p>Namespace definition with tools.build.api and Pretty Print</p> build.clj<pre><code>(ns build\n  (:require\n   [clojure.tools.build.api :as build-api]\n   [clojure.pprint :as pprint]))\n</code></pre> <p>Namespace definition with tools.build.api and Pretty Print</p> build.clj<pre><code>(ns build\n  (:require\n   [clojure.tools.build.api :as build-api]\n   [deps-deploy.deps-deploy :as deploy-api]\n   [clojure.pprint :as pprint]))\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#build-configuration","title":"Build configuration","text":"<p>Define a hash-map containing keys and values required to build the project.</p> Service UberjarLibrary Jar <p>Define a project configuration for building an Uberjar file to run a service using the <code>java -jar</code> command.</p> <p>The Uberjar can be deployed to run the service in test, staging and production environments.</p> <p>Clojure Service build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Project configuration\n\n(def project-config\n  \"Project configuration to support build tasks\"\n  {:class-directory \"target/classes\"\n   :main-namespace  'practicalli/project-name/service\n   :project-basis   (build-api/create-basis)\n   :uberjar-file    \"target/practicalli-servicename-standalone.jar\"})\n\n(defn config\n  \"Display build configuration\"\n  [config]\n  (pprint/pprint (or config project-config)))\n\n;; End of Build configuration\n;; ---------------------------------------------------------\n</code></pre> <p>Define a project configuration for building a jar file for deployment on Clojars and Maven Central, or a private repository. </p> <ul> <li><code>pom-template</code> is the standard structure for generating a pom.xml file, required by Maven repositories, i.e. Clojars.org and Maven Central</li> <li><code>project-config</code> specific values for building the project, e.g. name, version, etc.</li> <li><code>config</code> function to pretty print the build configuration</li> </ul> <p>Clojure Library build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build configuration\n\n(defn- pom-template\n  \"Standard structure for a `pom.xml` file, a Maven project configuration \n  required to deploy libraries to Clojars.org, Maven Central or private Maven repositories\n  https://maven.apache.org/guides/introduction/introduction-to-the-pom.html\"\n  [project-version]\n  [[:description \"FIXME: add purpose of library.\"]\n   [:url \"https://github.com/organisation/project-name\"]\n   [:licenses\n    [:license\n     [:name \"Creative Commons Attribution-ShareAlike 4.0 International\"]\n     [:url \"https://creativecommons.org/licenses/by-sa/4.0/\"]]]\n   [:developers\n    [:developer\n     [:name \"Organisation name\"]]]\n   [:scm\n    [:url \"https://github.com/organisation/project-name\"]\n    [:connection \"scm:git:https://github.com/organisation/project-name.git\"]\n    [:developerConnection \"scm:git:ssh:git@github.com:organisation/project-name.git\"]\n    [:tag (str \"v\" project-version)]]])\n\n\n(def project-config\n  \"Project configuration to support build tasks\"\n  (let [library-name 'net.clojars.organisation/project-name\n        version \"0.1.0-SNAPSHOT\"]\n    {:library-name     library-name\n     :project-version  version\n     :jar-file         (format \"target/%s-%s.jar\" (name library-name) version)\n     :project-basis    (build-api/create-basis)\n     :class-directory  \"target/classes\"\n     :src-directory    [\"src\"]\n     :target-directory \"target\"\n     :pom-config       (pom-template version)}))\n\n\n(defn config\n  \"Display build configuration\"\n  [config]\n  (pprint/pprint (or config project-config)))\n;; End of Build configuration\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#build-task","title":"Build Task","text":"Service UberjarLibrary Jar <p>Define Clojure functions to run the required build tasks</p> <ul> <li><code>clean</code> to remove build artefacts, e.g. <code>target</code> directory</li> <li><code>Uberjar</code> creates a Jar file for a Clojure library, ready for publishing</li> </ul> <p>Clojure Service build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build tasks\n\n(defn clean\n  \"Remove a directory\n  - `:path '\\\"directory-name\\\"'` for a specific directory\n  - `nil` (or no command line arguments) to delete `target` directory\n  `target` is the default directory for build artefacts\n  Checks that `.` and `/` directories are not deleted\"\n  [directory]\n  (when\n   (not (contains? #{\".\" \"/\"} directory))\n   (build-api/delete {:path (or (:path directory) \"target\")})))\n\n\n(defn uberjar\n  \"Create an archive containing Clojure and the build of the project\n  Merge command line configuration to the default project config\"\n  [options]\n  (let [config (merge project-config options)\n        {:keys [class-directory main-namespace project-basis uberjar-file]} config]\n    (clean \"target\")\n    (build-api/copy-dir {:src-dirs   [\"src\" \"resources\"]\n                         :target-dir class-directory})\n\n    (build-api/compile-clj {:basis     project-basis\n                            :class-dir class-directory\n                            :src-dirs  [\"src\"]})\n\n    (build-api/uber {:basis     project-basis\n                     :class-dir class-directory\n                     :main      main-namespace\n                     :uber-file uberjar-file})))\n\n;; End of Build tasks\n;; ---------------------------------------------------------\n</code></pre> <p>Define Clojure functions to run the required build tasks</p> <ul> <li><code>clean</code> to remove build artefacts, e.g. <code>target</code> directory</li> <li><code>jar</code> creates a Jar file for a Clojure library, ready for publishing</li> <li><code>install</code> a built jar into the local Maven repository, e.g. `~/.m2/repository/</li> <li><code>publish</code> a built jar to Clojars.org </li> </ul> <p>Clojure Library build tasks</p> build.clj<pre><code>;; ---------------------------------------------------------\n;; Build tasks\n\n(defn clean\n  \"Remove a directory\n  - `:path '\\\"directory-name\\\"'` for a specific directory\n  - `nil` (or no command line arguments) to delete `target` directory\n  `target` is the default directory for build artefacts\n  Checks that `.` and `/` directories are not deleted\"\n  [directory]\n  (when (not (contains? #{\".\" \"/\"} directory))\n    (build-api/delete {:path (or (:path directory) \"target\")})))\n\n(defn jar \"Run the CI pipeline of tests (and build the JAR).\"\n  [config]\n  (clean \"target\")\n  (let [config (project-config config)\n        class-directory (config :class-directory)]\n    (println \"\\nWriting pom.xml...\")\n    (build-api/write-pom (merge (pom-template config)))\n    (println \"\\nCopying source...\")\n    (build-api/copy-dir {:src-directory [\"resources\" \"src\"] :target-directory class-directory})\n    (println \"\\nBuilding JAR...\" (:jar-file config))\n    (build-api/jar config))\n  config)\n\n(defn install\n  \"Install a built JAR in the local Maven repository, e.g. `.m2/repository`\"\n  [config]\n  (let [config (project-config config)]\n    (build-api/install config))\n  config)\n\n(defn publish \n  \"Publish the built JAR to Clojars.\" \n  [config]\n  (let [{:keys [jar-file] :as config} (project-config config)]\n    (deploy-api/deploy\n     {:installer :remote :artifact (build-api/resolve-path jar-file)\n      :pom-file (build-api/pom-path (select-keys config [:library-name :class-directory]))}))\n  config)\n\n;; End of Build tasks\n;; ---------------------------------------------------------\n</code></pre>"},{"location":"clojure-cli/projects/package/tools-build/#resources","title":"Resources","text":"<p> Clojure.org tools.build Guide</p> <p> Clojure.org tools.build API Docs</p> <p> Clojure.org tools.build release information</p>"},{"location":"clojure-cli/projects/templates/","title":"Creating projects from templates","text":"<p>Creating projects using a template is a quick way to get started or create a common .  A template will create the project structure, add libraries and even include example code.</p> <p>deps-new provides Clojure CLI specific templates and  Practicalli Project Templates provides production level templates with a REPL Reloaded workflow</p> deps-new built-in templates <p>The deps-new built-in templates for creating a project - <code>app</code> - simple project for a running application (uberjar) - <code>lib</code> - simple project for a library (jar) - <code>scratch</code> - a <code>deps.edn</code> file and <code>src/scratch.clj</code> - <code>template</code> - project for defining a custom template</p> Practicalli Project Templates <p> Practicalli Project Templates provide production level templates that include Practicalli REPL Reloaded Workflow tools, Docker &amp; Compose configurations, Makefile tasks for a consistent command line UI and GitHub workflows to manage quality of code and configuration.</p> <ul> <li><code>practicalli/minimal</code> - essential tools, libraries and example code</li> <li><code>practicalli/application</code> - general Clojure production level project template </li> <li><code>practicalli/service</code> - production level web services template with component management, Http-kit, Reitit and Swagger</li> <li><code>pracicalli/landing-page</code> - simple clojurescript website with bulma.io CSS and Figheel-main build tool. </li> </ul> clj-new provides Leiningen format templates <p>The Practicalli <code>:project/new</code> alias provides the seancorfield/clj-new tool which can use a wide range of templates (although some may only create Leinginen projects).  This project has been archived and deps-new is the recommended approach.</p> <p>Migrate to a Clojure CLI project if the template does not include a <code>deps.edn</code> file</p> <p> Clojure Projects with the REPL video demonstrates shows how to use clj-new</p> <p><code>clj-new</code> can create projects from <code>deps.edn</code> and Leiningen templates. A wide range of templates have been created by the Clojure community which can be found by searching on Clojars.org:</p> <ul> <li>clj-templates website - leiningen and boot templates</li> <li>deps.edn projects</li> <li>Leiningen projects</li> </ul>"},{"location":"clojure-cli/projects/templates/#add-deps-new","title":"Add deps-new","text":"<p>Add deps-new via a Clojure CLI user alias or  install as a tool.</p>  Practicalli Clojure CLI ConfigAlias Definitions <p><code>:project/create</code> alias provided by  Practicalli Clojure CLI Config runs the  seancorfield/deps-new tool to create Clojure CLI specific projects. </p> <p><code>:project/create</code> alias includes the  Practicall Project templates , extending the range of available templates</p> <p>Create the following alias definitions in the Clojure CLI user configuration, e.g. <code>$XDG_CONFIG_HOME/clojure/deps.edn</code> or <code>$HOME/.clojure/deps.edn</code> Clojure CLI user deps.edn configuration - :aliases {}<pre><code>:project/create\n{:replace-deps {io.github.seancorfield/deps-new\n                {:git/tag \"v0.5.2\" :git/sha \"253f32a\"}\n                io.github.practicalli/project-templates\n                {:git/tag \"2023-08-02\" :git/sha \"eaa11fa\"}}\n :exec-fn      org.corfield.new/create\n :exec-args    {:template practicalli/minimal\n                :name practicalli/playground}}\n</code></pre></p>"},{"location":"clojure-cli/projects/templates/#create-a-project","title":"Create a project","text":"<p>Open a terminal window and change to a suitable folder and create a project.  </p> <p>Create a project using the <code>:project/create</code> alias.</p> <p>The <code>practicalli/minimal</code> template and <code>practicalli/playground</code> name are used if <code>:template</code> and <code>:name</code> arguments are not specified.</p> <pre><code>clojure -T:project/create\n</code></pre> <p>The <code>-T</code> execution option runs the tool with Clojure.exec which uses keywords to specify the options for creating the project.</p> <p>Use the form <code>domain/app-or-lib-name</code> to specify a project name, typically with a company name or Git Service account name as the <code>domain</code>.</p> <p><code>:template</code> can be one of the deps-new built-in templates (<code>app</code>, <code>lib</code>) or one of the  Practicalli Project Templates.</p> <p>Create a project using the <code>practicalli/application</code> template and random-function name. </p> <pre><code>clojure -T:project/create :template practicalli/application :name practicalli/random-function\n</code></pre>"},{"location":"clojure-cli/projects/templates/#run-project-in-a-repl","title":"Run Project in a REPL","text":"<p>Change into the directory and test the project runs by starting a REPL with Terminal REPL</p> <pre><code>cd playground &amp;&amp; clojure -M:repl/rebel\n</code></pre> <p>A repl prompt should appear.</p> <p>Type code expressions at the repl prompt and press RETURN to evaluate them.</p> <pre><code>(+ 1 2 3 4 5)\n</code></pre> Try the project with your preferred editor <p>Using a Clojure aware editor, open the playground project and run the REPL.  Then write code expressions in the editor and evaluate them to see the result instantly.</p>"},{"location":"clojure-cli/projects/templates/#running-the-project","title":"Running the project","text":"<p>Run project with or without an alias:</p> <pre><code>clojure -M:alias -m domain.app-name\nclojure -M -m domain.app-name\n</code></pre> <p>In the project <code>deps.edn</code> file it can be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.</p> <pre><code>:project/run\n{:ns-default domain.main-namespace\n :exec-fn -main\n :exec-args {:port 8888}}\n</code></pre> <p>Then the project can be run using <code>clojure -X:project/run</code> and arguments can optionally be included in this command line, to complement or replace any default arguments in <code>exec-args</code>.</p>"},{"location":"clojure-cli/projects/templates/design-templates/","title":"Design templates","text":"<p>Create a custom template project for yourself, your team / organisation or an open source project</p> <p>Either copy one of the Practicalli Project Templates or create a base template project</p> <pre><code>clojure -T:project/create :template template :name domain/template-name\n</code></pre> Local only template <p>If a template is only used by yourself locally, then all that is needed is a <code>deps.edn</code> config with deps-new, <code>resources/domain/template-name/</code> directory containing a <code>template.edn</code> and files to make up the new project and optionally a <code>src/domain/template-name.clj</code> for programmatic transform</p>"},{"location":"clojure-cli/projects/templates/design-templates/#add-project-files","title":"Add project files","text":"<p><code>resources/domain/project_name/</code> directory contains files that are used to create a new project when using the template.</p> <p><code>resources/domain/project_name/template.edn</code> defines the declarative copy rules that manage where files are copied too, allowing for renaming of files and directories.</p>"},{"location":"clojure-cli/projects/templates/design-templates/#deps-new-template-project","title":"deps-new template project","text":"<p>deps-new specification defined with clojure.spec</p> <pre><code>(s/def ::root string?)\n(s/def ::description string?)\n(s/def ::data-fn symbol?)\n(s/def ::template-fn symbol?)\n(s/def ::files (s/map-of string? string?))\n(s/def ::open-close (s/tuple string? string?))\n(s/def ::opts #{:only :raw})\n(s/def ::dir-spec (s/cat :src string?\n                         :target (s/? string?)\n                         :files (s/? ::files)\n                         :delims (s/? ::open-close)\n                         :opts (s/* ::opts)))\n(s/def ::transform (s/coll-of ::dir-spec :min-count 1))\n(s/def ::template (s/keys :opt-un [::data-fn ::description ::root ::template-fn ::transform]))\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#use-template-locally","title":"Use template locally","text":"<p>Create projects from the new template locally by defining a Clojure CLI user alias using :local/root that points to the root directory of the template project.</p> <pre><code>  :project/create-local\n  {:replace-deps {io.github.seancorfield/deps-new\n                  {:git/tag \"v0.5.2\" :git/sha \"253f32a\"}\n                  practicalli/project-templates\n                  {:local/root \"/home/practicalli/projects/practicalli/project-templates/\"}}\n   :exec-fn      org.corfield.new/create\n   :exec-args    {:template practicalli/minimal\n                  :name practicalli/playground}}\n</code></pre> <p>Create a new project with the <code>project/create-local</code> alias</p> <pre><code>clojure -T:project/create-local :template domain/template-name\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#unit-tests","title":"Unit tests","text":"<p>Each template should have a unit test that checks against the deps-new template specification (written in clojure.spec)</p> <p>Once the unit test pass, create a new project from the template just created</p> <p>Checks should be made of the following aspects of a new project created with the new template.</p> <ul> <li>check library dependency versions</li> <li>run main and exec functions</li> <li>run test runner</li> <li>test buld task clean and jar | uberjar</li> </ul> <p>template.edn contains a declarative configuration of the project a template will generate</p> <p><code>src/domain/template-name.clj</code></p> <p><code>test/domain/template_name_test.clj</code> defines a unit test with <code>clojure.test</code> and <code>clojure.spec</code> which test the <code>practicalli/template/service/template.edn</code> configuration.</p>"},{"location":"clojure-cli/projects/templates/design-templates/#template-specification","title":"Template specification","text":"<p>The template configuration is tested against the <code>org.corfield.new/template</code> specification</p> <p>Specification defined with clojure.spec</p> <pre><code>(s/def ::root string?)\n(s/def ::description string?)\n(s/def ::data-fn symbol?)\n(s/def ::template-fn symbol?)\n(s/def ::files (s/map-of string? string?))\n(s/def ::open-close (s/tuple string? string?))\n(s/def ::opts #{:only :raw})\n(s/def ::dir-spec (s/cat :src string?\n                         :target (s/? string?)\n                         :files (s/? ::files)\n                         :delims (s/? ::open-close)\n                         :opts (s/* ::opts)))\n(s/def ::transform (s/coll-of ::dir-spec :min-count 1))\n(s/def ::template (s/keys :opt-un [::data-fn ::description ::root ::template-fn ::transform]))\n</code></pre>"},{"location":"clojure-cli/projects/templates/design-templates/#publish-template","title":"Publish template","text":"<p>Templates are a shared Git repository, so push the template project to GitHub</p> <p>Include the shared repository within an alias definition within the Clojure CLI user deps.edn configuration, e.g. Practicalli Clojure CLI Config.</p> <p>Create a new project with the template using the alias.</p> <pre><code>clojure -T:project/create :template domain/template-name :name domain/project-name\n</code></pre> <p>:project/crate includes Practicalli Project Templates</p> <p>Practicalli Clojure CLI Config has been updated to include the practicalli/project-templates dependency, making available all the Practicalli templates.</p> <p>Default values for template.edn keys can also be defined in the <code>:exec-args {}</code> of an alias for the project template <pre><code>  :exec-args {:template practicalli/service\n              :name practicalli.gameboard/service}\n</code></pre></p>"},{"location":"clojure-cli/projects/templates/practicalli/","title":"Practicalli Project Templates","text":"<p>Practicalli Project templates provides tools for a REPL Reloaded Workflow and several production grade project configurations. </p> <p><code>:project/create</code> alias defined in  Practicalli Clojure CLI Config provides` provides seancorfield/deps-new tool for creating projects, including the  Practicalli Project Templates</p> <pre><code>clojure -T:project/create \n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/#available-templates","title":"Available Templates","text":"<p>Use the <code>:template</code> command line argument to specify a project template to generate the new Clojure project.</p> <ul> <li><code>practicalli/minimal</code> - essential tools, libraries and example code</li> <li><code>practicalli/application</code> - general Clojure production level project template </li> <li><code>practicalli/service</code> - production level web services template with Http-kit, Reitit and Swagger. Optional <code>: component</code> management with <code>:donut</code> or <code>:integrant</code></li> <li><code>pracicalli/landing-page</code> - simple clojurescript website with bulma.io CSS and Figheel-main build tool. </li> </ul> <p>Create service project with      Donut System components</p> <pre><code>clojure -T:project/create :template practicalli/service :name practicalli/todo-list :component :donut\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/#common-template-design","title":"Common Template Design","text":"<p> practicalli/project-templates provide production level templates that include Practicalli tools, Docker &amp; Compose configurations, Makefile tasks for a consistent command line UI and GitHub workflows to manage quality of code and configuration.</p>"},{"location":"clojure-cli/projects/templates/practicalli/#custom-user-namespace","title":"Custom user namespace","text":"<p>Practicalli <code>dev/user.clj</code> adds tools to the REPL on start up</p> <ul> <li><code>mulog_events.clj</code> custom publisher sends log events to portal</li> <li><code>portal.clj</code> launch portal data inspector and set log global context</li> <li><code>system_repl.clj</code> Component services e.g. donut-party/system, integrant REPL</li> <li><code>user.clj</code> provides help for custom user namespace, loads portal, mulog and tools.namespace.repl to support reloading Clojure code</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/#make-tasks","title":"Make tasks","text":"<p><code>Makefile</code> defines targets used across Practicalli projects, following the  make standard targets for users</p> <ul> <li><code>all</code>  calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean</li> <li><code>deps</code> download library dependencies (depend on <code>deps.edn</code> file)</li> <li><code>dist</code> create a distribution tar file for this program or zip deployment package for AWS Lambda</li> <li><code>lint</code> run lint tools to check code quality  - e.g MegaLinter which provides a wide range of tools</li> <li><code>format-check</code> report format and style issues for a specific programming language</li> <li><code>format-fix</code> update source code files if there are format and style issues for a specific programming language</li> <li><code>pre-commit</code> run unit tests and code quality targets before considering a Git commit</li> <li><code>repl</code> run an interactive run-time environment for the programming language</li> <li><code>test-unit</code> run all unit tests</li> <li><code>test-ci</code> test running in CI build (optionally focus on integration testing)</li> <li><code>clean</code> remove files created by any of the commands from other targets (i.e. ensure a clean build each time)</li> </ul> <p>Practicalli Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.</p> <ul> <li><code>docker-build</code> build Clojure project and run with docker compose</li> <li><code>docker-build-clean</code> build Clojure project and run with docker compose, removing orphans</li> <li><code>docker-down</code> shut down containers in docker compose</li> <li><code>swagger-editor</code> start Swagger Editor in Docker</li> <li><code>swagger-editor-down</code> stop Swagger Editor in Docker</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/#docker","title":"Docker","text":"<p>Docker configuration builds and runs the Clojure project in a Docker container, orchestrating with other services including a Database.</p> <p>The service and application project templates include the following files</p> <ul> <li><code>Dockerfile</code> multi-stage build and run, with JVM optomisations for a Docker container </li> <li><code>.dockerignore</code> patterns to opomise copying of files to the docker build image</li> <li><code>compose.yaml</code> configuration for orchestrating additional services, e.g. postgresql database</li> </ul>"},{"location":"clojure-cli/projects/templates/practicalli/application/","title":"Practicalli Application template","text":"<p>Create a general Clojure application with REPL Reloaded workflow.</p>"},{"location":"clojure-cli/projects/templates/practicalli/application/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.</p> <p>Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/","title":"Practicalli Landing Page","text":"<p>Build simple websites and landing pages using ClojureScript and figwheel-main.</p> <pre><code>clojure -T:project/create :template landing-page :name practicalli/website-name\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/landing-page/#template-design","title":"Template design","text":"<p>Configuration files</p> <ul> <li><code>deps.edn</code> project dependencies and aliases defining figwheel builds</li> <li><code>dev.cljs.edn</code> development build configuration</li> <li><code>live.cljs.edn</code> live build configuration (GitHub pages deployment by default)</li> <li><code>figwheel-main.edn</code> general figwheel configuration</li> </ul> <p>Clojure code</p> <ul> <li><code>src/project/landing-page.clj</code> compose components to render the website</li> <li><code>src/project/components.clj</code> functions that define component and associated helper functions</li> <li><code>src/project/data.clj</code> data structure passed in part or whole to each component, via the <code>landing-page</code>.</li> </ul> <p><code>project.data</code> namespace defines an example data structure as a static value (def).  Use an atom to contain the data structure if the data should be updated by components in the project.</p>"},{"location":"clojure-cli/projects/templates/practicalli/minimal/","title":"Practicalli Minimal Project Template","text":"<p>A Clojure project with minimal dependencies and example code, useful for experimenting or building a new project from a minimal setup.</p>"},{"location":"clojure-cli/projects/templates/practicalli/minimal/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.</p> <p>Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/projects/templates/practicalli/service/","title":"Practicalli Service template","text":"<p>Develop web services and APIs using the <code>practicalli/service</code> template.</p> <pre><code>clojure -T:project/create :template practicalli/service\n</code></pre> <p>The <code>practicalli/services</code> includes:</p> <ul> <li>http-kit provides an HTTP web server responding to HTTP requests</li> <li>reitit routing</li> <li>mulog event logging and publisher</li> <li>Portal data inspector</li> <li>Makefile with common Practicalli tasks</li> </ul> <p>A component system can be included by providing the <code>:component :donut</code> or <code>:component integrant</code> command line arguments.</p>"},{"location":"clojure-cli/projects/templates/practicalli/service/#component-systems","title":"Component systems","text":"<p>Components in the system can be managed during development by evaluating functions in the REPL.</p> <ul> <li><code>(start)</code> starts all components in order</li> <li><code>(stop)</code> stops  all components in order</li> <li><code>(restart)</code> reload changed namespaces and restart all components in order</li> <li><code>(system)</code> prints out the system configuration</li> </ul> <p>The <code>system-repl.clj</code> defines the functions to manage components, using the chosen component library, e.g. Donut system, Integrant REPL.</p> <p>When running the application from the command line, the <code>src/domain/project/service/-main</code> function calls the initialisation of components and creates a var called <code>running-system</code> that contains the initialised system components.  <code>-main</code> contains a shutdown hook that responds to SIGTERM signals, triggering a shutdown of components in the <code>running-system</code>.</p> Donut SystemIntegrant <p>Include Donut system configuration and REPL functions</p> <pre><code>clojure -T:project/create :template practicalli/service :component :donut\n</code></pre> <ul> <li><code>src/domain/project/system.clj</code> defines the system components</li> <li><code>dev/system-repl.clj</code> defines funtions to manage the system components</li> </ul> <p>Each component is defined within the <code>system</code> namespace in the <code>domain.project.system/main</code> hash-map.  Each component definition has a start and stop function, optionally passing configuration options and environment variables for that component.</p> <p>Include Integrant system configuration and Integrant REPL functions to support development</p> <pre><code>clojure -T:project/create :template practicalli/service :component :integrant\n</code></pre> <ul> <li><code>src/domain/project/system.clj</code> defines the system components</li> <li><code>dev/system-repl.clj</code> defines funtions to manage the system components</li> </ul> <p>Each component is started with an init multi-method with a the specific component name (keyword).  Each <code>init</code> multi-method provides the specific Clojure code to start the component.</p> <p>A <code>halt</code> multi-method is provided for each component that requires shutting down, e.g. http server, database pool, logging publisher, etc.</p> <p>During development and testing, the components are managed from the <code>user</code> namespace by evaluating the <code>(start)</code>, (stop) or <code>(restart)</code> functions.</p>"},{"location":"clojure-cli/projects/templates/practicalli/service/#using-the-project","title":"Using the project","text":"<p>Run the REPL</p> <pre><code>make repl\n</code></pre> <p>The REPL prompt is displayed using Rebel for a rich UI experience.  Portal data inspector window is displayed and all evaluation results and mulog events are automatically sent to Portal.</p> <p>An nREPL server is running in the background for connecting Clojure aware editors.</p> <p>Run tests (stopping on first failing test)</p> <pre><code>make test\n</code></pre>"},{"location":"clojure-cli/repl/","title":"Clojure REPL","text":"<p>The REPL is the environment in which all Clojure code runs, whether that be during development, testing or in production systems.</p> <p>A Terminal REPL provides a simple way to interact with the REPL, sending code expressions for evaluation and returning results. </p> <p>Use a  terminal REPL for </p> <ul> <li>quick experiments</li> <li>long running processes (e.g. http severs running Clojure) </li> <li>interact with the REPL state and manage components (e.g restarting system components, querying UI component state or services system state).</li> <li>a REPL process separate from a specific editor control</li> </ul> <p>REPL connected Editor</p> <p>A Clojure aware editor connected to the REPL is used for the majority of Clojure development.  One or more expressions from a source code file can be sent to the REPL for evaluation, displaying the results inline.</p>"},{"location":"clojure-cli/repl/#rebel-terminal-repl-ui","title":"Rebel Terminal REPL UI","text":"<p>Rebel is a REPL terminal UI that provides auto-completion, function call syntax help and documentation, themes and key binding styles to enhance the development experience.  Clojure tools also include a REPL with a minimal interface by default.</p> <p> </p>"},{"location":"clojure-cli/repl/#install-rebel","title":"Install Rebel","text":"Practicalli Clojure CLI ConfigDefine Rebel AliasClojure CLI REPL <p><code>:repl/rebel</code> alias is provided by  Practicalli Clojure CLI Config to run rebel readline.</p> <p><code>:repl/reloaded</code> alias runs Rebel with tools to support the  Practicalli REPL Reloaded, providing a custom REPL startup with support for Portal data inspector and Mulog event logs.</p> <p>Both aliases will start an nREPL server for  Clojure aware editors to connect.</p> <p>Rebel libraries are downloaded the first time the Rebel alias is used.</p> <p>Add an alias called <code>:repl/rebel</code>to the user <code>deps.edn</code> configuration, e.g. <code>~/.config/clojure/deps.edn</code></p> <p>Basic Rebel terminal UI alias</p> ~/.config/clojure/deps.edn<pre><code>:repl/rebel \n{:extra-deps {com.bhauman/rebel-readline {:mvn/version \"0.1.5\"}}\n :main-opts  [\"-m\" \"rebel-readline.main\"]}\n</code></pre> <p>Rebel terminal UI alias with nREPL for editor connection</p> ~/.config/clojure/deps.edn<pre><code>:repl/rebel\n{:extra-deps {nrepl/nrepl                {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl          {:mvn/version \"0.31.0\"}\n              com.bhauman/rebel-readline {:mvn/version \"0.1.4\"}}\n :main-opts  [\"-e\" \"(apply require clojure.main/repl-requires)\"\n              \"--main\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"\n              \"-f\" \"rebel-readline.main/-main\"]}\n</code></pre> <p> Practicalli Clojure CLI Config contains aliases for a basic terminal UI and a headless (non-interactive) terminal UI, each starting an nREPL server for editor connection.</p> <p>Alias definitions for a basic terminal UI REPL</p> <p>Interactive client REPL with nREPL server for Clojure Editor support <pre><code>:repl/basic\n{:extra-deps {nrepl/nrepl {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl {:mvn/version \"0.28.7\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"\n              \"--interactive\"]}\n</code></pre></p> <p>Headless REPL with nREPL server for Clojure Editor support <pre><code>:repl/headless\n{:extra-deps {nrepl/nrepl {:mvn/version \"1.0.0\"}\n              cider/cider-nrepl {:mvn/version \"0.28.7\"}}\n :main-opts  [\"-m\" \"nrepl.cmdline\"\n              \"--middleware\" \"[cider.nrepl/cider-middleware]\"]}\n</code></pre></p> <p>To have a basic terminal UI REPL prompt use the <code>:repl/basic</code> alias to start a REPL process with nREPL connection.</p> <pre><code>clj -M:repl/basic\n</code></pre> <p>To only have the REPL process without a REPL prompt, use the <code>:repl/headless</code> aliase to start a REPL process with nREPL connection.  This approach is useful to separate the REPL output from the editor whilst keeping all the interaction with the REPL via the editor.</p> <pre><code>clj -M:repl/headless\n</code></pre> Terminal REPL and Editor <p>Including an nREPL server when starting the REPL allows clojure ware editors to connect to the REPL process, providing a more effective way to write and extend Clojure code.</p> <p>An external REPL can still be of use even when only evaluating code in a Clojure editor. Separating the REPL process from the editor process allows the editor to be closed, upgraded or swapped for a different editor without having to end the REPL session.  Different editors could be connected to the same REPL to use particular features they provide.</p> <p>A REPL process can be long running, staying alive for days, weeks or months when working on larger projects.  Avoiding stop and start of the REPL maintains state in the REPL, maintaining the flow of the Clojure workflow.</p>"},{"location":"clojure-cli/repl/#customize-rebel-readline","title":"Customize Rebel Readline","text":"<p><code>:repl/help</code> in the repl prompt shows the Rebel configuration options</p> <p>Set configuration options in a <code>rebel_readline.edn</code> file, in <code>$XDG_CONFIG_HOME/clojure/</code> or <code>$HOME/.clojure</code></p> Practicalli Rebel Readline Configuration options $XDG_CONFIG_HOME/clojure/rebel_readline.edn<pre><code>;; ---------------------------------------------------------\n;; Rebel Readline Configuration\n;;\n;; Customise use and appearance\n;; ---------------------------------------------------------\n\n{;; Vi or Emacs style key-map\n ;; :viins or :emacs. Default :emacs\n :key-map     :viins\n\n ;; Color theme - light or dark\n ;; :color-theme :light-screen-theme\n :color-theme :dark-screen-theme\n\n ;; Enable syntax highlight. Default true}\n :hihighlight true\n\n ;; Enable complete on tab. Default true}\n :completion  true\n\n ;; Enable function documentation Default true\n :eldoc  true\n ;; auto indent code on newline. Default true}\n :indent true\n\n ;; rebind root *out* during read to protect linereader, Default true}\n :redirect-output true\n\n ;; Custom key-bindings applied after all other \n :key-bindings {}}\n</code></pre>"},{"location":"clojure-cli/repl/#next-steps","title":"Next Steps","text":"<p> Code In The REPL </p> <p> Managing Libraries In The REPL </p> <p> Help In The REPL </p> <p> Custom REPL Startup </p> <p> REPL Uncovered </p>"},{"location":"clojure-cli/repl/coding/","title":"Coding in the REPL","text":"<p>Clojure code can be typed into the REPL directly and the result instantly returned.  Code can also be loaded from a project source code files, to run pre-written code.</p> Clojure Editors are the main tool for writing code <p>An editor connected to a Clojure REPL and evaluating from source code files is the most effective way for writing Clojure code.  </p> <p>Evaluating code in an editor automatically uses the correct namespace, avoiding the need to change namespaces or fully qualify function calls. Evaluation results can be shown in-line, as comments next to the code or in a data inspector.  </p> <p>Editors provide structural editing and Clojure syntax checking, along with general editor features. and </p>"},{"location":"clojure-cli/repl/coding/#using-the-repl","title":"Using the REPL","text":"<p>Use the <code>clojure</code> command to start a REPL with Rebel, or the <code>clj</code> wrapper with the Clojure CLI REPL (requires <code>rlwrap</code> binary).</p> Rebel REPLClojure CLI REPL <p>Start a Clojure REPL with Rebel terminal UI which also starts an nREPL server which a Clojure editor can connect too.</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>A REPL prompt displays ready to evaluate a Clojure expression.</p> <p> </p> <p>Start a Clojure REPL with a basic UI which also starts an nREPL server which a Clojure editor can connect too.</p> <pre><code>clj -M:repl/basic\n</code></pre> <p>The <code>clj</code> wrapper requires <code>rlwrap</code> binary.</p> <p>A REPL prompt displays ready to evaluate a Clojure expression.</p> Project dependencies automatically downloaded on REPL start <p>When a REPL is started from the root of a Clojure project the project dependencies are automatically downloaded (unless previously downloaded to the local maven cache, <code>.m2/</code>) and project specific paths are added, e.g. <code>src</code> tree.</p> Use REPL with a Clojure project <p>A REPL can run without a Clojure project, however, libraries and code are simpler to manage within project source and configuration files.</p>"},{"location":"clojure-cli/repl/coding/#repl-start-state","title":"REPL start state","text":"<p>The Clojure REPL always starts in the <code>user</code> namespace.</p> <p>During startup the the <code>clojure.core</code> functions are required (made available) in the user namespace, so <code>(map inc [1 2 3])</code> can be called without specifying the <code>clojure.core</code> namespace in which those functions are defined.</p> <p>If clojure.core were not required, then the expression would be <code>(clojure.core/map clojure.core/inc [1 2 3])</code></p>"},{"location":"clojure-cli/repl/coding/#evaluating-code","title":"Evaluating code","text":"<p>Type Clojure code at the <code>=&gt; user</code> REPL prompt</p> <p>Press <code>Enter</code> to evaluate the code and see the result.</p> <p> </p> <p>Up and Down navigate the REPL history, providing an efficient way to evaluate the same code many times.</p> <p>In Rebel, typing part of function name shows matches available, Tab to cycle through the choices, Enter to select.</p> <p> </p>"},{"location":"clojure-cli/repl/coding/#load-code-from-file","title":"Load code from file","text":"<p>Clojure code is usually saved in files and each file has a namespace definition that matches the file path, using the <code>ns</code> function. The file <code>src/practicalli/playground.clj</code> has the namespace <code>practicalli.playground</code></p> <pre><code>(ns practicalli.playground)\n</code></pre> <p>Requiring the namespace of a file will evaluate (load) the code from that file in the REPL.</p> <pre><code>(require 'practicalli.playground)\n</code></pre> <p>Functions defined in that namespace can be called using their fully qualified names.  e.g. if the namespace contains a function called <code>main</code>, that function can be called using <code>(practicalli.playground/main)</code>.</p> Change namespaces <p>Change the namespace to <code>practicalli.playground</code> to call functions defined in that namespace by their unqualified function name, eg. <code>(main)</code>, rather than the fully qualified name, e.g. <code>(practicalli.playground/main)</code></p> <p><code>in-ns</code> will change change the current namespace to the one specified as an argument.</p> <pre><code>(in-ns 'practicalli.playground)\n</code></pre> <p>Now the <code>(main)</code> function can be called without having to include the full namespace name.</p> <p>Typically it is more efficient to stay in the <code>user</code> namespace and require all other namespaces required.</p>"},{"location":"clojure-cli/repl/coding/#reload-code-changes","title":"Reload code changes","text":"<p>The <code>:reload</code> option to <code>require</code> will load in any changes to a namespace that happened outside of the REPL, eg. using an editor to change the source code in the file.</p> <pre><code>(require 'practicalli.playground :reload)\n</code></pre> <p>Use the <code>:verbose</code> option when issues occur loading a particular namespace.  As the namespace being required may also require other namespaces, multiple namespaces may be loaded from one <code>require</code> expression.</p> <p><code>:verbose</code> shows a full list of the namespaces being loaded.</p> <pre><code>(require 'practicalli.playground :reload :verbose)\n</code></pre> Reload in Terminal REPL for unconnected editor <p>When using an editor that is not connected to the Clojure REPL, then reloading is an effective way of updating the code with all the changes saved in the file.</p>"},{"location":"clojure-cli/repl/coding/#close-repl","title":"Close REPL","text":"<p><code>:repl/quit</code> at the REPL prompt will end the REPL session and all code not saved to a file will be lost.</p> <p>Ctrl+c if the repl process does not return to the shell prompt.</p>"},{"location":"clojure-cli/repl/coding/#next-steps","title":"Next steps","text":"<p>Managing Library dependencies in REPL</p>"},{"location":"clojure-cli/repl/help/","title":"Help at the REPL","text":"<p>rebel readline provides tools to help you discover and use functions from clojure.core and any other libraries you add to the REPL.</p> <p><code>:repl/help</code> will show all the commands available for rebel readline</p> <p>Tab to autocomplete the current characters into a function name.  All functions that match the characters will be show, allowing quick discovery of functions available. Typing in the first few characters of a function and press</p> <p> </p> <p>Moving the cursor after the name of a function will show the signatures available, so a function can be called with the correct number and form of arguments.</p> <p> </p> <p>Ctrl+C+Ctrl+d on a function name shows the docstring to help understand the functions purpose.</p> <p> </p> <p><code>clojure.repl/doc</code> function also shows the docstring of a function <code>(clojure.repl/doc doc)</code></p> <p>Ctrl+C+Ctrl+a on a name shows all the possible matching functions to help you discover what is available.  Tab through the list of matches, Enter to select a function</p> <p></p>"},{"location":"clojure-cli/repl/help/#rebel-commands","title":"Rebel Commands","text":"<p>Type <code>:repl/help</code> or <code>:repl</code> TAB to see a list of available commands.</p> Keybinding Description <code>:repl/help</code> Prints the documentation for all available commands. <code>:repl/key-bindings</code> search or list current key bindings <code>:repl/quit</code> Quits the REPL <code>:repl/set-color-theme</code> Change the color theme <code>:dark-screen-theme</code> <code>:light-screen-theme</code> <code>:repl/set-key-map</code> Change key bindings to given key-map, <code>:emacs</code> <code>:vicmd</code> <code>:viins</code> <code>:repl/toggle-color</code> Toggle ANSI text coloration on and off <code>:repl/toggle-completion</code> Toggle the completion functionality on and off <code>:repl/toggle-eldoc</code> Toggle the auto display of function signatures on and off <code>:repl/toggle-highlight</code> Toggle readline syntax highlighting on and off <code>:repl/toggle-indent</code> Toggle the automatic indenting of Clojure code on and off"},{"location":"clojure-cli/repl/help/#key-bindings","title":"Key-bindings","text":"Keybinding Description <code>Ctrl-C</code> aborts editing the current line <code>Ctrl-D</code> at the start of a line =&gt; sends an end of stream message <code>TAB</code> word completion or code indent when cursor in whitespace at the start of line <code>Ctrl-X_Ctrl-D</code> Show documentation for word at point <code>Ctrl-X_Ctrl-S</code> Show source for word at point <code>Ctrl-X_Ctrl-A</code> Show apropos for word at point <code>Ctrl-X_Ctrl-E</code> Inline eval for SEXP before the point <p>Examine key-bindings with the <code>:repl/key-bindings</code> command.</p>"},{"location":"clojure-cli/repl/libraries/","title":"Using Clojure libraries in the REPL","text":"<p>A library should be included as a dependency in order to use it within the REPL.</p> <p>Add library dependencies to the top level <code>:deps</code> key in a project <code>deps.edn</code> configuration file, or add via an alias if the library is use at development time.</p> <p>Aliases from a user configuration can also add optional libraries when running a REPL, e.g. Practicalli Clojure CLI config</p> <pre><code>{:paths [\"src\" \"resources\"]\n\n :deps\n {org.clojure/clojure {:mvn/version \"1.10.3\"}}\n\n :aliases\n {\n  :database/h2\n  {:extra-deps {com.h2database/h2                 {:mvn/version \"2.1.210\"}\n                com.github.seancorfield/next.jdbc {:mvn/version \"1.2.772\"}}}\n #_()}\n</code></pre> Finding libraries <p>Search for community libraries via the Clojars.org website</p> <p><code>clojure -M:search/libraries pattern</code> where pattern is the name of the library to search for.  Copy the relevant results into the project <code>deps.edn</code> file.</p> <p><code>clojure -M:search/libraries --format:merge pattern</code> will automatically add the library into the <code>deps.edn</code> file.</p> <p><code>clojure -X:deps find-versions :lib fully.qualified/library-name :n 5</code> returns the last 5 versions of the given library.</p>"},{"location":"clojure-cli/repl/libraries/#include-library","title":"Include library","text":"<p>Open a terminal and change to the root of the Clojure project directory, where the <code>deps.edn</code> file can be found.</p> <p>Start the REPL including the <code>:database/h2</code> alias to include every library defined in the <code>:deps</code> key and libraries in the <code>:database/h2</code> alias.  This example is using rebel readline rich terminal UI</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>This command will include</p> <p>Add aliases to include optional libraries, such as those used for development.  In this example, the H2 database and next.jdbc libraries are included along with those libraries in the <code>:deps</code> key of <code>deps.edn</code></p> <pre><code>clojure -M:database/h2:repl/rebel\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#load-namespace","title":"Load namespace","text":"<p>At the REPL prompt, require a namespace from the project to load all the code from that namespace and any namespaces required.</p> <p>If a project was created with the command <code>clojure -T:project/new :template app :name practicalli/status-monitor</code> then the main namespace will be <code>practicalli.status-monitor</code></p> <pre><code>(require '[practicalli.status-monitor])\n</code></pre> <p>The <code>require</code> function loads all the code from the main namespace.  When an <code>ns</code> form is read, required namespaces in the <code>ns</code> form are also loaded.</p>"},{"location":"clojure-cli/repl/libraries/#reloading-namespace","title":"Reloading namespace","text":"<p>Clojure is a dynamic environment, so changes to function definitions (<code>defn</code>) and shared symbol names (<code>def</code>) can be updated without restarting the REPL.</p> <p><code>require</code> loads the code from the specified namespace.  Using the <code>:reload</code> option forces the namespace to be loaded again, even if it was already loaded.</p> <p>When changes are made to a namespace in the source code file, <code>:reload</code> ensures those changes become the code running in the REPL</p> <pre><code>(require '[practicalli.status-monitor] :reload)\n</code></pre> <p>If errors occur when loading or reloading the namespace with require, the <code>:verbose</code> option will show all the namespaces that are loaded.  This may show issues or help track down conflicting namespaces or functions.</p> <pre><code>(require '[practicalli.status-monitor] :reload :verbose)\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#hotload-libraries","title":"Hotload libraries","text":"Hotload Libraries in the REPL <p><code>add-libs</code> function from the <code>clojure.tools.deps.alpha</code> library is an experimental approach to hot-loading library dependencies without having to restart the REPL or add those dependencies to the project <code>deps.edn</code>.  This provides a simple way to try out libraries.</p> <p>hotload libraries secion for more details and how to use with Clojure editors.</p> <p>Start a REPL session using Clojure CLI with the <code>:lib/hotload alias</code>, including rebel readline for an enhance REPL terminal UI.</p> <pre><code>clojure -M:lib/hotload:repl/rebel\n</code></pre> <p></p> <p>Require the <code>clojure.tools.deps.alpha</code> library and refer the <code>add-libs</code> function.  The <code>add-libs</code> function can then be called without having to use an alias or the fully qualified name.</p> <pre><code>(require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n</code></pre> <p>Hotload a library into the REPL using the <code>add-lib</code> function in the following form, where <code>domain/library</code> is the fully qualified name of the library and <code>RELEASE</code> is a string of the version number of that library to use.</p> <pre><code>(add-libs '{domain/library {:mvn/version \"RELEASE\"}})\n</code></pre> <p>Multiple libraries can be hot-loaded in a single <code>add-libs</code> expression</p> <pre><code>(add-libs '{hhgttg/meaning {:mvn/version \"4.2.0\"}\n            eternity/room  {:mvn/version \"1.0.1\"}})\n</code></pre>"},{"location":"clojure-cli/repl/libraries/#hotload-hiccup-in-a-terminal-repl","title":"Hotload hiccup in a terminal REPL","text":"<p>The hiccup library converts clojure structures into html, where vectors represent the scope of keywords that represent html tags.</p> <p>Load the hiccup library using add-libs</p> <pre><code>(add-libs '{hiccup/hiccup {:mvn/version \"2.0.0-alpha2\"}})\n</code></pre> <p>Require the hiccup library so its functions are accessible from the current namespace in the REPL.</p> <pre><code>(require '[hiccup.core :as hiccup])\n</code></pre> <p>Enter an expression using the <code>hiccup/html</code> function to convert a clojure data structure to html.</p> <pre><code>(hiccup/html [:div {:class \"right-aligned\"}])\n</code></pre> <p>The hiccup expression returns a string of the html code.</p> <p></p>"},{"location":"clojure-cli/repl/repl-uncovered/","title":"Read, Evaluate Print Loop (REPL)","text":"<p>The REPL provides a fast, powerful and fun way to develop code and is the hard of the Clojure developers workflow.  The REPL allows you to quickly test out designs and your domain knowledge of the system you are building, easily accommodating multiple designs to help you evaluate the best approach.</p> <p>Starting a REPL is the first thing you do after creating or downloading a project.</p> <p>The REPL allows you to run any existing code, write new code and change code.  Each time you can see the results of your code instantly.</p> <p>The REPL can run all of your code or simply get the result of an individual expression.  You can inspect run-time values and continually develop your code without having to restart each time.</p> <p>Hint If you are not using the REPL for your Clojure development you are missing out on a highly productive workflow.  Once you start using a REPL as part of you development cycle you will feel lost without one.</p>"},{"location":"clojure-cli/repl/repl-uncovered/#how-the-repl-works-simple-version","title":"How the REPL works (simple version)","text":"<p>A Clojure REPL has 4 stages:</p> <ul> <li>Read - read in the code</li> <li>Evaluate - evaluate the code</li> <li>Print - show the results</li> <li>Loop - on to the next expression</li> </ul> <p>Its useful to understand the difference between Read and Evaluate, especially when you get as far as writing macro's for Clojure.</p>"},{"location":"clojure-cli/repl/repl-uncovered/#the-reader","title":"The Reader","text":"<p>The Reader parses the Clojure source code, form by form, producing the Clojure data structures an [Abstract Syntax Tree] (AST).</p> <p>Due to the syntax of Clojure, much of the source code is already in the right structure.  Any macros will be expanded into its Clojure structure.</p> <p>These data structures are then evaluated: Clojure traverses the data structures and performs actions like function application or var lookup based on the type of the data structure.</p> <p>For example, when Clojure reads the text (+ 1 2), the result is a list data structure whose first element is a + symbol, followed by the numbers 1 and 2. This data structure is passed to Clojure\u2019s evaluator, which looks up the function corresponding to + and applies that function to 1 and 2.</p> <p></p>"},{"location":"clojure-cli/repl/repl-uncovered/#the-reader_1","title":"The Reader","text":"<p>Hint Clojure is a homoiconic language, which is a fancy term describing the fact that Clojure programs are represented by Clojure data structures. This is a very important difference between Clojure and most other programming languages.  It means that Clojure is defined in terms of the evaluation of data structures and not in terms of the syntax of character streams/files.</p> <p>It is quite common, and easy, for Clojure programs to manipulate, transform and produce other Clojure programs.</p> <p>The reader has syntax defined in terms of characters, and the Clojure language has syntax defined in terms of symbols, lists, vectors, maps etc. The reader is represented by the function read, which reads the next form (not character) from a stream, and returns the object represented by that form.</p> <p>There are also Reader Macros that define special rules on top of the Clojure syntax.  They give the language some additional syntax sugar, making your Clojure code compact.  See the reference section on reader macros for more information</p>"},{"location":"clojure-cli/repl/repl-uncovered/#evaluator","title":"Evaluator","text":"<p>The Evaluator takes the data structure as an argument (from the Reader) and processes it using rules corresponding to the data structure\u2019s type, returning the result.</p> <p>To evaluate a symbol, Clojure looks up what the symbol refers to.</p> <p>To evaluate a list, Clojure looks at the first element of the list and calls a function, macro, or special form.</p> <p>Any other values including strings, numbers and keywords simply evaluate to themselves.</p> <p>Hint Read the section on Reading, Evaluation and Macros from BraveClojure to see examples of the REPL process.</p>"},{"location":"clojure-cli/repl/troubleshooting/","title":"Troubleshooting the REPL","text":"<p>The aspects to consider when a REPL process fails to run are:</p> <ul> <li>Some code expressions are not correct</li> <li>Dependencies are not available</li> <li>Project (or editor) misconfigured</li> </ul>"},{"location":"clojure-cli/repl/troubleshooting/#code-expression-failing","title":"Code expression failing","text":"<p>All code in the project must compile and be syntactically correct, even if that code is in a rich <code>(comment ,,,)</code> block.</p> <p>A Clojure expression following a Reader comment, <code>#_</code> does not have to compile, however it must be syntactically correct, i.e. balanced parentheses.</p> <p>Add a line comment, <code>;;</code>, to any code that is suspected of not compiling or being syntactically incorrect (or delete that code).</p>"},{"location":"clojure-cli/repl/troubleshooting/#editor-repl-fails-to-start","title":"Editor REPL fails to start","text":"<p>If using a jack-in approach with the editor to start the repl, run a terminal UI REPL with an nREPL server and try connecting to that REPL from the editor.</p> <p>Clojure CLI repl - rebel terminal UI</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Then require the main namespace and see if there are issues, optionally using :verbose to see which libraries are being loaded.</p> <pre><code>(require '[practicalli.service] :verbose)\n</code></pre> <p>If the REPL runs correctly, it is likely the editor configuration is missing something or is incorrect.  Check the configuration for running a Clojure project with the editor.</p>"},{"location":"clojure-cli/repl/troubleshooting/#terminal-ui-repl-fails-in-project","title":"Terminal UI REPL fails in project","text":"<p>If the REPL does not run correctly or the namespace fails to load, run a repl without any extra development dependencies (tooling, dev libraries, etc) and load the main namespace</p> <pre><code>clj\n</code></pre>"},{"location":"clojure-cli/repl/troubleshooting/#repl-doesnt-start-in-any-project","title":"REPL doesnt start in any project","text":"<p>Run the <code>clojure</code> command in a directory that is not part of any existing Clojure project.  This will run the REPL with only the <code>org.clojure/clojure</code> dependency</p> <p>Run <code>clojure -Sdescribe</code> to check that the Clojure CLI is using the correct configuration files and is the expected version.</p> <p>If a REPL prompt appears, then Clojure CLI is working.  If a REPL prompt does not appear, then reinstall the Clojure CLI or upgrade to a newer version.</p> <p>Clojure CLI install - Practicalli Guide</p>"},{"location":"clojure-cli/repl/troubleshooting/#repl-starts-but-requiring-code-fails","title":"REPL starts but requiring code fails","text":"<p>Creating a new project is a fast way to check development tooling is working correctly.  A project can be created with <code>clojure -T:project/create</code> (with  Practicalli Clojure CLI Config installed)</p> <p>If a REPL process starts correctly for a new project but not the existing project, then its most likely one or more expressions in the existing project that are causing an error or the project <code>deps.edn</code> configuration.</p> <p>Copy the <code>deps.edn</code> configuration from the existing project to the root of the new project (or just the <code>:deps</code> section of the <code>deps.edn</code> configuration).  Run the REPL again using the <code>clojure</code> command.  If the REPL fails then it is likely an issue with the exiting projects <code>deps.edn</code> file or one of the dependencies</p>"},{"location":"clojure-cli/repl/troubleshooting/#dependency-issues","title":"Dependency issues","text":"<p>Projects typically depend on many other libraries and sometimes those libraries depend on other libraries too.</p> <p>When running the <code>clojure</code> command to run a terminal UI REPL, libraries are retrieved from remote repositories (Maven Central, Clojars.org) and stored in a local cache <code>~/.m2/repositories</code></p> <p>If a dependency is not available then a warning should state which library cannot be downloaded and from which repository</p> <p>Check the extent of the dependencies for the existing project:</p> <pre><code>clojure -Stree\n</code></pre> <p>Use the antq tool to check for a newer version of a dependency</p> <pre><code>clojure -T:project/outdated\n</code></pre> <p>If libraries are likely to become unavailable (i.e. old versions) then consider creating a local repository service with Artefactory or Nexus, which can share library depenencies between development teams of an organisation.</p>"},{"location":"clojure-editors/","title":"Editors for Clojure development","text":"<p>The best editor to use for learning Clojure is the editor already familiar with (or want to learn).</p> <p>Use SublimeText &amp; ClojureSublimed if unsure where to start as it will be the simplest tool to use.</p>"},{"location":"clojure-editors/#clojure-editor-features","title":"Clojure editor features","text":"<p>An ideal Clojure editor includes the these core features</p> <ul> <li>running / connecting to a REPL process</li> <li>evaluation results inline or in a repl window (fast feedback on what the code does)</li> <li>syntax highlighting (including highlight of matching parens)</li> <li>structural editing to ensure parens are balanced when writing and refactor code</li> <li>data inspector to visualise large and nested data, or connection to  data inpector tools</li> </ul> <p></p>"},{"location":"clojure-editors/#clojure-aware-editors","title":"Clojure aware editors","text":"<p>Emacs (Spacemacs, Doom, Prelude), Neovim (Conjure) and VSCode (Calva) are the most common open source Editors for Clojure and ClojureScript development.</p> <p>SublimeText and IntelliJ are commercial editors (with limited free editions) which also provide Clojure support</p> EmacsNeovimVSCodeSublimeTextPulsar (Atom)Intellij <p></p> <p>Emacs is a very powerful editor with thousands of packages enabling a person to do almost any digital task concievable.  Emacs is highly extensible via the ELisp programming language used to write configuration and the numerous Emacs packages. Native Compilation of Emacs packages dramatically speeds up many common tasks.</p> <p>Emacs uses CIDER and Clojure LSP for a feature rich clojure development experience.</p> <p>Use one of the popular community configurations for Emacs or visit the  CIDER documentation to learn how to add Clojure support to Emacs.</p> SpacemacsPrelude EmacsDoom EmacsVanilla Emacs &amp; Cider <p></p> <p> Spacemacs is a community configuration bringing  Emacs features and  Vim style editing together.  Spacemacs uses a mnemonic menu system that makes it easy to learn and provides detailed documentation for configuring and using Emacs.</p> <p> Practicalli Spacemacs provides a guide to Clojure development, vim-style editing, documenting with org-mode, Git version control with Magit, Issues &amp; Pull Requests with Forge and dozens of other features.</p> <p> Practicalli Spacemacs Config contains a customised configuration for Clojure development and supporting tools.</p> Free Desktop XDG ConfigClassic Config <pre><code>git clone https://github.com/practicalli/spacemacs.d.git $XDG_CONFIG_HOME/spacemacs`\n</code></pre> <pre><code>git clone https://github.com/practicalli/spacemacs.d.git $HOME/.spacemacs.d`\n</code></pre> <p>The Practicalli configuration should replace the <code>~/.spacemacs</code> file if it exists</p> <p>Spacemacs install guide - Practicalli Spacemacs</p> <p><p> </p></p> <p> Emacs Prelude is an easy to use Emacs configuration for Emacs newcomers and lots of additional power for Emacs power users, from the author of CIDER - the definitive Clojure IDE for Emacs.</p> <p>Prelude uses the traditional chorded key bindings to drive Emacs, e.g. Ctrl+c Ctrl+c to evaluate the current top-level form.</p> <p> Prelude Install Guide</p> <p></p> <p> Doom Emacs is a community configuration for Emacs that provides a minimalistic configuration that is readily customisable.  Doom Emacs is most suited to those coming from Vim and have a strong experience for multi-modal editing.</p> <p> Practicalli Doom Emacs Book</p> <p> Practicalli Doom Emacs Config contains a customised configuration for Clojure development and supporting tools.</p> Free Desktop XDG ConfigClassic Config <p><pre><code>git clone https://github.com/practicalli/doom-emacs-config.git $XDG_CONFIG_HOME/doom`\n</code></pre> The Practicalli configuration should replace the <code>~/.config/doom/</code> directory created by the <code>doom install</code> command.</p> <p><pre><code>git clone https://github.com/practicalli/doom-emacs-config.git $HOME/.doom.d`\n</code></pre> The Practicalli configuration should replace the <code>~/.doom.d/</code> directory created by the <code>doom install</code> command.</p> <p> </p> <p>Emacs 29 is recommended as it includes native compilation support and optomised JSON support which is valuable for Language Server Protocol servers.</p> <p>Emacs is available for Linux, MacOSX and Windows.</p> Ubuntu / DebianHomebrew / MacOSXWindowsMsys2 <p><code>apt-cache show emacs</code> to check available versions of Emacs in the Ubuntu package manager. If version 28 is available, install Emacs using the Ubuntu package manager.</p> <pre><code>sudo apt install emacs\n</code></pre> <p>Additional versions of Emacs are available via the Ubuntu Emacs Team Personal Package Archive.</p> <p><code>sudo apt install emacs-snapshot</code> package to use the latest nightly build of Emacs, although be aware that some things may break.</p> Build Emacs 29 from source <p>Building Emacs 29 from source code on Ubuntu is relatively straight forward task, although it will take a little time to compile.  Building Emacs allows customisation of some features, such as native compilatin of elisp to enhance the performance of Emacs.</p> <p>Emacs Plus from Homebrew provides many options, including native compilation and Spacemacs Icon for application launchers.</p> <pre><code>brew tap d12frosted/emacs-plus`\nbrew install emacs-plus@28 --with-native-comp --with-spacemacs-icon\n</code></pre> <p>Emacs.app is installed to: <code>/usr/local/opt/emacs-plus@28</code></p> <p>Optionally run Emacs plus as a service <pre><code>brew services start d12frosted/emacs-plus/emacs-plus@28\n</code></pre></p> <p>Run <code>emacs</code></p> <p>Get a hot cup of something as Emacs native compilation compiles all the things.</p> <p>The Spacemacs README lists other options for MacOSX.</p> <p>Download Emacs-28.2 from the GNU repository and extract the zip file to <code>%AppData%/local/Programs/emacs</code>.</p> <p>Alternatively, if you are using the Chocolatey package manager then install Emacs version 28</p> <p>Add the Emacs directory to the <code>PATH</code> variable in your user account environment variables.</p> <p>To start Emacs run the command <code>runemacs.exe</code>.  You can also pin this to the start menu or task bar.</p> Access to common Unix tools <p>Command line tools, such as <code>diff</code>, are used by Emacs.  To have these command line tools available in Windows, install Emacs as above but then run emacs from a Unix shell such as GitBash.</p> <p>Install Emacs (64bits build) with the following:</p> <pre><code>pacman -S mingw-w64-x86_64-emacs\n</code></pre> <p>Once Emacs is installed, add the cider package for essential Clojure support.</p> <p>Cider Install Guide</p> <p></p> <p>Neovim is a hyper-extensible text editor that runs in a terminal, configured with the Lua programming language. Configuration can also be written in Fennel (a lisp dialect), using nfnl to generate Lua code.</p> <p>Neovim is based on multi-model editing (e.g. normal, insert, visual editing states) providing a highly effective tool for writing code, configuration and documentation.</p> <p>Neovim includes Treesitter which understands the syntax of a great many programming and configuration languages, which can be coupled with analysist from Language Sever Protocol (LSP) servers to provide live feedback on code quality.</p> <p></p> <p>Conjure provides Clojure interactive (REPL) development, supporting Clojure CLI, Leiningen and Babashka projects (as well as several other Lisp dialects and interesting languages)</p> <p>Try the Conjure interactive <code>:ConjureSchool</code> tutorial which only requires a recent version of neovim <pre><code>curl -fL conjure.fun/school | sh\n</code></pre> </p> <p><code>:q</code> to quit the tutorial.</p> Practicalli AstroNvimPracticalli NeovimSpaceVimVimIced <p> Practicalli Neovim - AstroNvim install</p> <p>AstroNvim community configuration for Neovim provides an engaging UI, using Lazy plugin manger and Mason to manage LSP servers, format &amp; lint tools.</p> <p> Practicalli AstroNvim Config provides a user configuration for Astronvim, including Conjure, parinfer, LSP server and treesitter parser for Clojure development.</p> <p> Practicalli Neovim provides an install and user guide for Neovim and Conjure for Clojure development, folloiwng a REPL driven workflow.</p> <p> </p> <p>Archived project - to be reimplemented using nfnl rather than aniseed.  Recommend using AstroNvim instead.</p> <p> Practicalli Neovim Config Redux configuration for Neovim which adds  a range of Neovim plugins for a rich development experience.</p> <ul> <li>mnemonic of key bindings to make adoptiong Neovim easier</li> <li>visual navigation for files, project, environment variables and any other list items</li> <li>version control and GitHub issue &amp; pull request management</li> </ul> <p> Conjure provides interactive environment for evaluating Clojure code and providing inline results (or see results in an Heads Up Display or Log buffer).</p> <p> Practicalli Neovim provides an install and user guide for Neovim and Conjure for Clojure development, folloiwng a REPL driven workflow.</p> <p></p> <p>SpaceVim is a fully featured vim experience that includes a minimal Clojure development environment based around vim-fireplace</p> <p>Follow the Quick Start Guide to install SpaceVim</p> <p>Add the Clojure layer to the SpaceVim custom configuration file ~/.SpaceVim.d/init.toml<pre><code>[[layers]]\n  name = \"lang#clojure\"\n</code></pre></p> <p>SpaceVim quickstart guide SpaceVim - Clojure Layer</p> <p></p> <p>Interactive Clojure Environment for Vim8/Neovim, aimed at the more experienced Vim/Neovim user.</p> <p>vim-iced uses vim-sexp for structural editing</p> <p>vim-plug is required to install the vim-iced packages.</p> <p>vim-iced documentation</p> <p></p> <p>VS Code is a freely available editor build on open source and available for Linux, MacOS and Microsoft Windows.</p> <p>VSCode Getting Started Guide</p> <p>VS Code has a large marketplace of extensions, proiding additional tools for a complete development environment.</p> <p>Calva is the most commonly used extension for Clojure support and aims to provide similar features to Emacs Cider (and uses some of the same Clojure libraries).</p> <p>Clojure CLI User Aliases not directly supported</p> <p>Calva does not support Clojure CLI user aliases directly (only project deps.edn).  A JSON mapping must be added to the Calva configuration for each user alias (duplicating configuration)</p> <p>Practicalli recommends starting the Clojure REPL in a terminal and specifying the required Clojure CLI user aliases, using Calva connect once the REPL has started.</p> <p>VSpaceCode provides a mnemonic menu to drive VS Code by keyboard alone, vim editing and rich Git client (edamagit).  VSpaceCode extension also provides key bindings for common Calva commands.  Users experienced with Neovim and Emacs (Spacemacs / Doom) will find this extension makes VS Code easiter to use than vanilla VS Code or VS Code with an Neovim backend.</p> <p>Clover provides a mininal, highly customisable environment using Socket REPL.</p> CalvaVSpaceCodeClover <p></p> <p>The Calva extension adds Clojure REPL support to VS Code editor, including Clojure LSP, formatting, structural editing and many other features.</p> <p>Calva is under active development and the #calva channel on the Clojurians Slack community can be supportive.</p> <p>Calva Getting Started Guide Calva - VS Code Marketplace</p> <p><p> </p></p> <p></p> <p>VSpaceCode is a Spacemacs-like community configuration for Microsoft VS Code. Drive VS Code entirely from the keyboard, using easy to remember mnemonic keys for all commands and full vim-stile editing tools.</p> <p>Calva extension must be added as it is not part of VSpaceCode, although Calva commands are included in the VSpaceCode mneomoic menu when a Clojure file is open.</p> <p>Edamagit is a sophisticated text based Git client (like magit for Emacs) is also included in the VSpacemacs extension.</p> <p>Practicalli VSpaceCode install guide Practicalli VSpaceCode user guide</p> <p></p> <p><p> </p></p> <p>Clover is a Socket REPL based development tool for Clojure with some ClojureScript support (not including Figwheel).</p> <p>Clojure GitLab repository includes usage details.</p> <p></p> <p>SublimeText 4 is a lightweight and feature rich text editor, especially of interest to those that like a simple and uncluttered UI.  SublimeText is a commercial project although has free trial version available (check conditions of use).</p> <p>Clojure-Sublimed provides Clojure support for SublimeText 4, with support for Clojure &amp; Edn syntax, code formatting and an nREPL client to connect to a Clojure REPL process.</p> <p>Tutkain is an Sublime 4 package that supports Clojure development (self-described as alpha software).</p> <p>Build configuration to start a REPL</p> <p>Clojure Sublime connects to a REPL via an nREPL server.  Run a terminal REPL using Clojure CLI, Leinginen (<code>lein repl</code>) or Shadow-cljs (<code>shadow-cljs watch app</code>)</p> <p>Alternatively, configure Clojure Sublimed to run a REPL process by creating a new build system via Tools \u00bb Build System \u00bb New Build System. The following example starts a Clojure CLI REPL with nREPL server and assumes Java and Clojure CLI are installed. <pre><code>{\"env\": {\"JAVA_HOME\": \"/path/to/java\"},\n \"cmd\": [\"/usr/local/bin/clojure\", \"-Sdeps\", \"{:deps {nrepl/nrepl {:mvn/version \\\"1.0.0\\\"}}}\", \"-M\", \"-m\", \"nrepl.cmdline\"]}\n</code></pre> Run a REPL process via Tools \u00bb Build With\u2026 and connect to the REPL using the command Clojure Sublimed: Connect</p> <p>SublimeText install Clojure-Sublimed install SublimeText Documentation</p> <p></p> <p>Pulsar Community-led Hyper-Hackable Editor is a very new project to create a community version of the Atom editor from GitHub.</p> <p>Chlorine plugin provides a Clojure and ClojureScript development environment using Socket-REPL integration</p> <p>Pulsar Community-led Hyper-Hackable Editor Pulsar Chlorine plugin</p> <p>Atom not actively developed</p> <p>Atom will be archived on December 15 2022 with no further updates from GitHub team</p> <p>Consider using VSCode with Clover or Calva plugin or help support the evolution of the Pulsar project</p> <p>Cursive may be an appropriate choice for people from a Java background who are already familiar with IntelliJ.  Cursive will run static analysis of Clojure code when opening a Clojure project, as IntelliJ does with other languages.</p> <p>Follow the Cursive user guide to configure IntelliJ and install Cursive.</p> <p>Requires license for commercial development</p> <p>There is a free license when development is not for commercial projects, however, a license must be purchased for each developer working on a commercial project.</p> <p>IntelliJ &amp; Cursive install guide</p> <p></p>"},{"location":"clojure-editors/clojure-lsp/","title":"Language Server Protocol","text":"<p> Language Server Protocol provides a standard to provide a common set of development tools, e.g.  code completion, syntax highlighting, refactor and language diagnostics.</p> <p>Each language requires a specific LSP server implementation.</p> <p>An editor or plugin provides an LSP client that uses data from language servers, providing information about source code and enabling development tools to understand the code structure.</p>"},{"location":"clojure-editors/clojure-lsp/#clojure-lsp","title":"Clojure LSP","text":"<p> clojure-lsp is an implementation of an LSP server for Clojure and ClojureScript languages.  Clojure LSP is built on top of  clj-kondo which provides the static analysis of Clojure and ClojureScript code.</p> <p>Most Clojure aware editors provide an LSP client.</p> <p></p>"},{"location":"clojure-editors/clojure-lsp/#install","title":"Install","text":"<p>Clojure LSP installation guide covers multiple operating systems.</p> LinuxHomebrew <p>Practicalli recommends downloading the <code>clojure-lsp-native-linux-amd64</code> from GitHub release page</p> <p>Extracts the <code>clojure-lsp</code> binary to <code>~/.local/bin/clojure-lsp</code></p> <p>Clojure LSP project provides a custom tap for installing the latest version.</p> <pre><code>brew install clojure-lsp/brew/clojure-lsp-native\n</code></pre> Homebrew default package deprecated <p>The <code>clojure-lsp</code> formula is deprecated and should not be used.</p> <p><code>brew remove clojure-lsp</code> if the default clojure-lsp was installed</p> <p>Check Clojure LSP server is working via the command line</p> <pre><code>clojure-lsp --version\n</code></pre> Editors may provide install mechanism for Clojure LSP <p>Spacemacs LSP layer will prompt to install a language server when first opening a file of a major mode where LSP is enabled.  E.g. when a Clojure related file is opened, the Clojure LSP server is downloaded if not installed (or not found on the Emacs path).</p> <p>Neovim package called mason manages the install of lint &amp; format tools as well as LSP servers, or an externally installed LSP server can also be used.</p> <p>VSCode Calva plugin includes the clojure-lsp server, although an external server can be configured.</p>"},{"location":"clojure-editors/clojure-lsp/#configure","title":"Configure","text":"Practicalli Clojure LSP Configuration <p>config.edn is the recommended configuration from Practicalli. <pre><code>;; ---------------------------------------------------------\n;; Clojure LSP user level (global) configuration\n;; https://clojure-lsp.io/settings/\n;;\n;; Complete config.edn example with default settings\n;; https://github.com/clojure-lsp/clojure-lsp/blob/master/docs/all-available-settings.edn\n;; default key/value are in comments\n;; ---------------------------------------------------------\n\n;; Refact config from all-available-settings example\n\n{;; ---------------------------------------------------------\n ;; Project analysis\n\n ;; auto-resolved for deps.edn, project.clj or bb.edn projects\n ;; :source-paths #{\"src\" \"test\"}\n\n ;; Include :extra-paths and :extra-deps from project &amp; user level aliases in LSP classpath\n ;;  :source-aliases #{:dev :test}\n :source-aliases #{:dev :test :dev/env :dev/reloaded}\n\n ;; Define a custom project classpath command, e.g. Clojure CLI\n ;; :project-specs [{:project-path \"deps.edn\"\n ;;                  :classpath-cmd [\"clojure\" \"-M:env/dev:env/test\" \"-Spath\"]}]\n ;; Check the default at clojure-lsp.classpath/default-project-specs\n ;; :project-specs []\n\n ;; ignore analyzing/linting specific paths\n :source-paths-ignore-regex [\"target.*\" \"build.*\" \"console-log-.*\"]\n\n ;; Additional LSP configurations to load from classpath\n ;; https://clojure-lsp.io/settings/#classpath-config-paths\n ;; :classpath-config-paths []\n\n ;; :paths-ignore-regex []\n\n ;; Watch for classpath changes\n ;; :notify-references-on-file-change true\n ;; :compute-external-file-changes true\n\n ;; Approach for linking dependencies\n ;; :dependency-scheme \"zipfile\"\n\n ;; generate and analyze stubs for specific namespaces on the project classpath\n ;; typically for closed source dependencies, e.g. datomic.api\n ;; https://clojure-lsp.io/settings/#stub-generation\n ;; :stubs {:generation {:namespaces #{}\n ;;                      :output-dir \".lsp/.cache/stubs\"\n ;;                     :java-command \"java\"}\n ;;        :extra-dirs []}\n\n ;; Java Sources from Ubuntu package openjdk-17-source\n ;; jdk-source-uri takes precedence\n ;; :java\n ;; {:jdk-source-uri \"https://raw.githubusercontent.com/clojure-lsp/jdk-source/main/openjdk-19/reduced/source.zip\"\n ;;  :home-path nil ;; jdk-source-uri takes precedence\n ;;  :download-jdk-source? false\n ;;  :decompile-jar-as-project? true}\n ;; :java\n ;; {:jdk-source-uri \"file:///usr/lib/jvm/openjdk-17/lib/src.zip\"}\n :java nil\n\n ;; End of Project analysis\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Linter configuration\n\n ;; clj-kondo Linter rules\n ;; https://github.com/clj-kondo/clj-kondo/blob/master/doc/config.md#enable-optional-linters\n ;; :linters {:clj-kondo {:level :on\n ;;                      :report-duplicates true\n ;;                      :ns-exclude-regex \"\"}\n ;;          :clj-depend {:level :info}} ;; Only if any clj-depend config is found\n\n ;; asynchronously lint project files after startup, for features like List project errors\n ;; :lint-project-files-after-startup? true\n\n ;; copy clj-kondo hooks configs exported by libs on classpath during startup\n ;; :copy-kondo-configs? true\n\n ;; End of Linter configuration\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Refactor code\n\n ;; Namespace format\n ;; :clean {:automatically-after-ns-refactor true\n ;;         :ns-inner-blocks-indentation :next-line\n ;;         :ns-import-classes-indentation :next-line\n ;;         :sort {:ns true\n ;;                :require true\n ;;                :import true\n ;;                :import-classes {:classes-per-line 3} ;; -1 for all in single line\n ;;                :refer {:max-line-length 80}}}\n\n  ;; Do not sort namespaces\n :clean {sort {:ns      false\n               :require false\n               :import  false}}\n\n ;; Automatically add ns form to new Clojure/Script files\n ;; :auto-add-ns-to-new-files? true\n\n ;; use ^private metadata rather than defn-\n ;; :use-metadata-for-privacy? false\n :use-metadata-for-privacy? true\n\n ;; Keep parens around single argument functions in thread macro\n ;; :keep-parens-when-threading? false\n :keep-parens-when-threading? true\n\n ;; End of Refactor code\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Clojure formatting configuration - cljfmt\n\n ;; location of cljfmt configuration for formatting\n ;; Path relative to project root or an absolute path\n ;; :cljfmt-config-path \".cljfmt.edn\"\n :cljfmt-config-path \"cljfmt.edn\"\n\n ;; Specify cljfmt configuration within Clojure LSP configuration file\n ;; :cljfmt {}\n\n ;; End of Clojure formatting configuration - cljfmt\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; Visual LSP components\n\n ;; :hover {:hide-file-location? false\n ;;         :arity-on-same-line? false\n ;;         :clojuredocs true}\n\n ;; :completion {:additional-edits-warning-text nil\n ;;              :analysis-type :fast-but-stale}\n\n ;; :code-lens {:segregate-test-references true}\n\n ;; LSP semantic tokens server support for syntax highlighting\n ;; :semantic-tokens? true\n\n ;; Documentation artefacts\n ;; :document-formatting?       true\n ;; :document-range-formatting? true\n\n ;; End of Visual LSP components\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; LSP general configuration options\n\n ;; Exit clojure-lsp if any errors found, e.g. classpath scan failure\n ;; :api {:exit-on-errors? true}\n\n ;; Synchronise whole buffer `:full` or only related changes `:incremental`\n ;; :text-document-sync-kind :full\n\n ;; End of LSP general configuration options\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; File locations\n\n ;; project analysis cache to speed clojure-lsp startup\n ;; relative path to project root or absolute path\n ;; :cache-path \".lsp/.cache\"\n\n ;; Absolute path\n ;; :log-path \"/tmp/clojure-lsp.*.out\"\n\n ;; End of file locations\n ;; ---------------------------------------------------------\n\n ;; ---------------------------------------------------------\n ;; LSP snippets\n ;; https://clojure-lsp.io/features/#snippets\n\n :additional-snippets\n [;; Documentation / comments\n\n  {:name \"comment-heading\"\n   :detail \"Comment Header\"\n   :snippet\n   \";; ---------------------------------------------------------\n    ;; ${1:Heading summary title}\n    ;;\n    ;; ${2:Brief description}\\n;; ---------------------------------------------------------\\n\\n$0\"}\n\n  {:name \"comment-separator\"\n   :detail \"Comment Separator\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\"}\n\n  {:name \"comment-section\"\n   :detail \"Comment Section\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\\n\\n\n    ;; End of $1\\n;; ---------------------------------------------------------\\n\\n\"}\n\n  {:name \"wrap-reader-comment\"\n   :detail \"Wrap current expression with Comment Reader macro\"\n   :snippet \"#_$current-form\"}\n\n  {:name \"rich-comment\"\n   :detail \"Create rich comment\"\n   :snippet\n   \"(comment\n      $0\n  #_()) ;; End of rich comment\"}\n\n  {:name \"rich-comment-rdd\"\n   :detail \"Create comment block\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n   (comment\n     $0\n   #_()) ; End of rich comment\"}\n\n  {:name \"rich-comment-hotload\"\n   :detail \"Rich comment library hotload\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n    (comment\n      ;; Add-lib library for hot-loading\n      (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n      (add-libs '{${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$3})\n      $0\n    #_()) ; End of rich comment block\"}\n\n  {:name \"wrap-rich-comment\"\n   :detail \"Wrap current expression with rich comment form\"\n   :snippet\n   \"(comment\n      $current-form\n      $0\n   #_()) ;; End of rich comment\"}\n\n  ;; Core functions\n\n  {:name \"def\"\n   :detail \"def with docstring\"\n   :snippet \"(def ${1:name}\\n  \\\"${2:doc-string}\\\"\\n  $0)\"}\n\n  {:name \"def-\"\n   :detail \"def private\"\n   :snippet \"(def ^:private ${1:name}\\n  \\\"${2:doc-string}\\\"\\n $0)\"}\n\n  {:name \"defn\"\n   :detail \"Create public function\"\n   :snippet \"(defn ${1:name}\\n  \\\"${2:doc-string}\\\"\\n   [${3:args}]\\n  $0)\"}\n\n  {:name \"defn-\"\n   :detail \"Create public function\"\n   :snippet \"(defn ^:private ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n\n  {:name \"ns\"\n   :detail \"Create ns\"\n   :snippet \"(ns ${1:name}\\n  \\\"${2:doc-string}\\\"\\n  ${3:require})\"}\n\n  ;; Clojure CLI alias snippets\n\n  {:name \"deps-alias\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}}$0\"}\n\n  {:name \"deps-alias-main\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :main-opts [\\\"-m\\\" \\\"${4:main namespace}\\\"]}$0\"}\n\n  {:name \"deps-alias-exec\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :exec-fn ${4:domain/function-name}\n     :exec-args {${5:key value}}}$0\"}\n\n  {:name \"deps-alias-main-exec\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}\n     :main-opts [\\\"-m\\\" \\\"${4:main namespace}\\\"]\n     :exec-fn ${4:domain/function-name}\n     :exec-args {${5:key value}}}$0\"}\n\n  {:name \"deps-maven\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$0\"}\n\n  {:name \"deps-git\"\n   :detail \"deps.edn Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n       {:git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-git-tag\"\n   :detail \"Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/tag \\\"${2:git-tag-value}\\\"\n       :git/sha \\\"${3:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-git-url\"\n   :detail \"Git URL dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/url \\\"https://github.com/$1\\\"\n       :git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n\n  {:name \"deps-local\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:local/root \\\"${2:/path/to/project/root}\\\"}$0\"}\n\n   ;; Requiring dependency snippets\n\n  {:name \"require-rdd\"\n   :detail \"require for rich comment experiments\"\n   :snippet \"(require '[${1:namespace} :as ${2:alias}]$3)$0\"}\n\n  {:name \"require\"\n   :detail \"ns require\"\n   :snippet \"(:require [${1:namespace}])$0\"}\n\n  {:name \"require-refer\"\n   :detail \"ns require with :refer\"\n   :snippet \"(:require [${1:namespace} :refer [$2]]$3)$0\"}\n\n  {:name \"require-as\"\n   :detail \"ns require with :as alias\"\n   :snippet \"(:require [${1:namespace} :as ${2:alias}]$3)$0\"}\n\n  {:name \"use\"\n   :detail \"require refer preferred over use\"\n   :snippet \"(:require [${1:namespace} :refer [$2]])$0\"}\n\n   ;; Unit Test snippets\n\n  {:name \"deftest\"\n   :detail \"deftest clojure.test\"\n   :snippet\n   \"(deftest ${1:name}-test\n            (testing \\\"${2:Context of the test assertions}\\\"\n            (is (= ${3:assertion-values}))$4)) $0\"}\n\n  {:name \"testing\"\n   :detail \"testing asserting group for clojure.test\"\n   :snippet \"(testing \\\"${1:description-of-assertion-group}\\\"\\n $0)\"}\n\n  {:name \"is\"\n   :detail \"assertion for clojure.test\"\n   :snippet \"(is (= ${1:function call} ${2:expected result}))$0\"}\n\n   ;; ---------------------------------------------------------\n   ;; Clojure LSP and Clj-kondo snippets\n\n  {:name \"lsp-ignore-redefined\"\n   :detail \"Ignore redefined Vars\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n            $0\"}\n\n   ;; End of Clojure LSP and Clj-kondo snippets\n   ;; ---------------------------------------------------------\n  ]\n  ;; End of LSP snippets\n  ;; ---------------------------------------------------------\n\n }\n</code></pre></p> <p>Include <code>:extra-paths</code> and <code>:extra-deps</code> from project &amp; user level aliases in LSP classpath.  e.g. support a custom <code>user</code> namespace in <code>dev/user.clj</code></p> <pre><code> :source-aliases #{:dev :test :env/dev :env/test :lib/reloaded}\n</code></pre> <p>Include Java Sources installed via Debian / Ubuntu package <code>openjdk-21-source</code> to support calls to Java Objects and Methods.</p> <pre><code> :java\n {:jdk-source-uri       \"file:///usr/lib/jvm/openjdk-21/lib/src.zip\" ;;\n  :home-path            nil ;; jdk-source-uri takes precedence\n  :download-jdk-source? false}\n</code></pre> <p>Disable Java analysis</p> <p>If not using Java Interop with Clojure, it can be an advantage to disable the Java analysis.  This should remove Java functions from autocomplete.</p> <pre><code>:java nil\n</code></pre> <p>Clean namespace <code>ns</code> forms but do not sort require names</p> <pre><code> :clean {:automatically-after-ns-refactor true\n         :ns-inner-blocks-indentation     :next-line\n         :ns-import-classes-indentation   :next-line\n         :sort {:ns      false\n                :require false\n                :import  false\n                :import-classes {:classes-per-line 3} ;; -1 for all in single line\n                :refer {:max-line-length 80}}}\n</code></pre> <p>Use <code>^private</code> metadata for private function definitions rather than <code>defn-</code></p> <pre><code> :use-metadata-for-privacy? true\n</code></pre> <p>Location of cljfmt configuration for formatting, path relative to project root.  The defaults for cljfmt are used, except <code>:remove-consecutive-blank-lines?</code> which is set to false to enable more readable code.</p> <pre><code> :cljfmt-config-path \"cljfmt.edn\"\n</code></pre> <p>cljfmt configuration included example <code>:indents</code> rules for clojure.core, compojure, fuzzy rules and examples used by the Clojure LSP maintainer.</p>"},{"location":"clojure-editors/clojure-lsp/#practicalli-snippets","title":"Practicalli snippets","text":"<p>Practicalli Snippets are defined in the <code>:additional-snippets</code> section of the Practicalli Clojure LSP config.</p>"},{"location":"clojure-editors/clojure-lsp/#docs-comments","title":"Docs / comments","text":"<ul> <li><code>comment-heading</code> - describe purpose of the namespace</li> <li><code>comment-separator</code> - logically separate code sections, helps identify opportunities to refactor to other name spaces</li> <li><code>comment-section</code> - logically separate large code sections with start and end line comments</li> <li><code>wrap-reader-comment</code> - insert reader comment macro, <code>#_</code> before current form, informing Clojure reader to ignore next form</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#repl-driven-development","title":"Repl Driven Development","text":"<ul> <li><code>rich-comment</code> - comment block</li> <li><code>rich-comment-rdd</code> - comment block with ignore :redefined-var for repl experiments</li> <li><code>rich-comment-hotload</code> - comment block with add-libs code for hotloading libraries in Clojure CLI repl</li> <li><code>wrap-rich-comment</code> - wrap current form with comment reader macro</li> <li><code>require-rdd</code> - add a require expression, for adding a require in a rich comment block for RDD</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#standard-library-functions","title":"Standard library functions","text":"<ul> <li><code>def</code> - def with docstring</li> <li><code>def-</code> - private def with docstring</li> <li><code>defn</code> - defn with docstring</li> <li><code>defn-</code> private defn with docstring</li> <li><code>ns</code> - namespace form with docstring</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#clojure-cli-depsedn-aliases","title":"Clojure CLI deps.edn aliases","text":"<ul> <li><code>deps-alias</code> - add Clojure CLI alias</li> <li><code>deps-maven</code> - add a maven style dependency</li> <li><code>deps-git</code> - add a git style dependency using <code>:git/sha</code></li> <li><code>deps-git-tag</code> - as above including <code>:git/tag</code></li> <li><code>deps-git-url</code> - add git style dependency using git url (url taken from dependency name as it is typed - mirrored placeholder)</li> <li><code>deps-local</code> - add a <code>:local/root</code> dependency</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#requiring-dependencies","title":"Requiring dependencies","text":"<ul> <li><code>require-rdd</code> - add a require expression, for adding a require in a rich comment block for RDD</li> <li><code>require</code> - simple require</li> <li><code>require-refer</code> - require with <code>:refer</code></li> <li><code>require-as</code> - require with <code>:as</code> alias</li> <li><code>use</code> - creates a require rather than the more troublesome use</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#unit-testing","title":"Unit testing","text":"<ul> <li><code>deftest</code> - creates a deftest with testing directive and one assertion</li> <li><code>testing</code> - creates a testing testing directive and one assertion</li> <li><code>is</code> - an assertion with placeholders for test function and expected results</li> </ul>"},{"location":"clojure-editors/clojure-lsp/#references","title":"References","text":"<ul> <li>LSP mode - A guide on disabling / enabling features - if the Emacs UI is too cluttered or missing visual features</li> <li>Configure Emacs as a Clojure IDE</li> <li>Language Server Protocol support for Emacs</li> </ul>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/","title":"Practicalli Snippets for Clojure LSP","text":"<p>Custom snippets created by Practicalli and added via the <code>:additional-snippets</code> key in the Clojure LSP configuration (<code>.lsp/config.edn</code> or user level configuration).  Snippets are defined as a vector of hash-maps</p> <pre><code>{:additional-snippets [{} {} {} ,,,]}\n</code></pre> <p>Practicalli Snippets available in practicalli/clojure-lsp-config</p> <p>Move or delete the clojure configuration directory and clone the  Practicalli Clojure CLI Config</p>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#documentation","title":"Documentation","text":"<p>A comment heading to describe the purpose and important information about the current namesapce.</p> <pre><code>  {:name \"comment-heading\"\n   :detail \"Comment Header\"\n   :snippet\n   \";; ---------------------------------------------------------\n    ;; ${1:Heading summary title}\n    ;;\n    ;; ${2:Brief description}\\n;; ---------------------------------------------------------\\n\\n$0\"}\n</code></pre> <p>A comment separator for marking logical sections within a namespace, useful for navigating code and identifying opportunities to refactor a namespace into multiple namespaces.</p> <pre><code>  {:name \"comment-separator\"\n   :detail \"Comment Separator\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\"}\n</code></pre> <p>A comment section with start and end titles for marking logical sections within a namespace, again for navigation and identifying opportunities to refactor a namespace.</p> <pre><code>  {:name \"comment-section\"\n   :detail \"Comment Section\"\n   :snippet\n   \";; ---------------------------------------------------------\\n;; ${1:Section title}\\n\\n$0\\n\\n\n    ;; End of $1\\n;; ---------------------------------------------------------\\n\\n\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#repl-driven-development","title":"REPL Driven Development","text":"<p>A rich comment block typically used to hold function calls to show how to make use of the important aspects of the current namespace.  For example, calls to <code>start</code>, <code>restart</code>, <code>stop</code> functions in a namespace that defines the service life-cycle.</p> <p>This provides a live executable guide to using the namespace, without being called if the whole namespace is evaluated.</p> <p>A commented expression is placed before the closing paren to ensure that closing paren is not folded up into the previous line.  This makes it easier to add further code to the rich comment block.</p> <pre><code>  {:name \"rich-comment\"\n   :detail \"Create rich comment\"\n   :snippet\n   \"(comment\n      $0\n  #_()) ;; End of rich comment\"}\n</code></pre> <p>A modified rich comment block with clj-kondo configuration to suppress warnings for duplicate function definition names, supporting alternative function implementations as part of a REPL driven development workflow.</p> <pre><code>  {:name \"rich-comment-rdd\"\n   :detail \"Create comment block\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n   (comment\n     $0\n   #_()) ;; End of rich comment\"}\n</code></pre> <p>Wrap an existing form in a rich comment</p> <pre><code>  {:name \"wrap-rich-comment\"\n   :detail \"Wrap current expression with rich comment form\"\n   :snippet\n   \"(comment\n      $current-form\n      $0\n   #_()) ;; End of rich comment\"}\n</code></pre> <p>Comment an existing form with the Clojure Comment macro, <code>_#</code></p> <pre><code>  {:name \"wrap-reader-comment\"\n   :detail \"Wrap current expression with Comment Reader macro\"\n   :snippet \"#_$current-form\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#hot-loading-library-dependencies","title":"Hot loading library dependencies","text":"<p>Clojure CLI projects can hotload library dependencies into a running Clojure REPL.  This requires starting a REPL with the <code>clojure.tools.deps.alpha</code> library as a dependency which can be done by including the <code>:lib/hotload</code> alias from practicalli/clojure-deps-edn.  Note this library is alpha and the API could change in future.</p> <p>Create a rich comment block that requires the <code>clojure.tools.deps.alpha</code> namespace and an <code>add-libs</code> expression to hotload one or more libraries in a hash-map.  Tab stops with placeholders are included for adding the first library to hotload.</p> <pre><code>  {:name \"rich-comment-hotload\"\n   :detail \"Rich comment library hotload\"\n   :snippet\n   \"#_{:clj-kondo/ignore [:redefined-var]}\n    (comment\n      ;; Add-lib library for hot-loading\n      (require '[clojure.tools.deps.alpha.repl :refer [add-libs]])\n      (add-libs '{${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$3})\n      $0\n    #_()) ;; End of rich comment block\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#core-functions","title":"Core functions","text":"<p>Create a public var using a <code>def</code> form with a doc-string, with placeholders for name and value.</p> <pre><code>  {:name \"def\"\n   :detail \"def with docstring\"\n   :snippet \"(def ${1:name}\\n  \\\"${2:docstring}\\\"\\n  $0)\"}\n</code></pre> <p>Create a private var using a <code>def</code> form with <code>^:private</code> meta data and a doc-string, with placeholders for name and value.</p> <pre><code>  {:name \"def-\"\n   :detail \"def private\"\n   :snippet \"(def ^:private ${1:name}\\n  \\\"${2:doc-string}\\\"\\n $0)\"}\n</code></pre> <p>A <code>defn</code> form with name, doc-string and args tab-stops</p> <pre><code>  {:name \"defn\"\n   :detail \"Create public function\"\n   :snippet \"(defn ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n</code></pre> <p>A <code>defn</code> form with private metatdata. Including name, doc-string and args tab-stops</p> <pre><code>  {:name \"defn-\"\n   :detail \"Create public function\"\n   :snippet \"(defn ^:private ${1:name}\\n  \\\"${2:docstring}\\\"\\n   [${3:args}]\\n  $0)\"}\n</code></pre> <p>A namespace form with name, doc-string and require tab-stop.</p> <pre><code>  {:name \"ns\"\n   :detail \"Create ns\"\n   :snippet \"(ns ${1:name}\\n  \\\"${2:docstring}\\\"\\n  ${3:require})\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#clojure-cli-aliases-and-library-dependencies","title":"Clojure CLI aliases and library dependencies","text":"<p>Add Clojure CLI alias to <code>deps.edn</code>, with an <code>:extra-paths</code> and <code>:extra-deps</code> section</p> <pre><code>  {:name \"deps-alias\"\n   :detail \"deps.edn alias with extra path &amp; deps\"\n   :snippet\n   \":${1:category/name}\n    {:extra-paths [\\\"${2:path}\\\"]\n     :extra-deps {${3:deps-maven or deps-git}}}$0\"}\n</code></pre> <p>Add a Maven style dependency to a Clojure CLI <code>deps.edn</code> project.</p> <pre><code>  {:name \"deps-maven\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:mvn/version \\\"${2:1.0.0}\\\"}$0\"}\n</code></pre> <p>Add a dependency from a Git repository, where the library is named after the remote Git repository, i.e io.github.user|org/library-name for the GitHub repository <code>https://github.com/user|org/library-name</code>.</p> <p>The <code>:git/sha</code> defines a specific commit to use for the dependency.</p> <pre><code>  {:name \"deps-git\"\n   :detail \"deps.edn Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n       {:git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n</code></pre> <p>Additionally a Git tag can be specified, enabling the use of the short SHA value for <code>:git/sha</code> (short sha is the first 7 characters of the 40 character SHA-1 value).</p> <p>A Git client can obtain the short form of a SHA from a Git repository</p> <pre><code>git rev-parse --short 1e872b59013425b7c404a91d16119e8452b983f2\n</code></pre> <pre><code>  {:name \"deps-git-tag\"\n   :detail \"Git dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/tag \\\"${2:git-tag-value}\\\"\n       :git/sha \\\"${3:git-sha-value}\\\"}$0\"}\n</code></pre> <p>If a library is not named after the domain of the Git repository, the URL of the Git repository must be specified using the <code>:git/url</code> key.</p> <pre><code>  {:name \"deps-git-url\"\n   :detail \"Git URL dependency\"\n   :snippet\n   \"${1:domain/library-name}\n      {:git/url \\\"https://github.com/$1\\\"\n       :git/sha \\\"${2:git-sha-value}\\\"}$0\"}\n</code></pre> <p>Add a library dependency that is a local Clojure project.</p> <pre><code>  {:name \"deps-local\"\n   :detail \"deps.edn Maven dependency\"\n   :snippet\n   \"${1:domain/library-name} {:local/root \\\"${2:/path/to/project/root}\\\"}$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#require-library-dependencies","title":"Require Library Dependencies","text":"<p>Require a library when using REPL driven development in a rich comment block, adding a <code>(require ,,,)</code> form when evaluating the use of a library without forcing it to be loaded when loading the namespace.</p> <pre><code>  {:name \"require-rdd\"\n   :detail \"require for rich comment experiments\"\n   :snippet \"(require '[${1:namespace} :as ${2:alias}]$3)$0\"}\n</code></pre> <p>A basic <code>:require</code> expression for an <code>ns</code> form.</p> <pre><code>  {:name \"require\"\n   :detail \"ns require\"\n   :snippet \"(:require [${1:namespace}])$0\"}\n</code></pre> <p>A <code>:require</code> expression for an <code>ns</code> form, including a <code>:as</code> directive to define an alias for the required namespace.</p> <pre><code>  {:name \"require-as\"\n   :detail \"ns require with :as alias\"\n   :snippet \"(:require [${1:namespace} :as ${2:alias}]$3)$0\"}\n</code></pre> <p>A <code>:require</code> expression for an <code>ns</code> form, including a <code>:refer</code> directive to include specific function definitions and vars by name.</p> <pre><code>  {:name \"require-refer\"\n   :detail \"ns require with :refer\"\n   :snippet \"(:require [${1:namespace} :refer [$2]]$3)$0\"}\n</code></pre> <p>It is idiomatic to use require with refer to pull in specific functions and vars from another namespace.  The <code>use</code> function is not recommended as it can easily pull more transitive dependencies into the current namespace, causing unexpected results</p> <pre><code>  {:name \"use\"\n   :detail \"require refer preferred over use\"\n   :snippet \"(:require [${1:namespace} :refer [$2]])$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/practicalli-snippets/#clojuretest-snippets","title":"Clojure.test snippets","text":"<p>When writing a <code>deftest</code>, a new assertion written may be better in a new group.  The <code>testing</code> snippet will create a new <code>testing</code> form and pull in the following assertion.</p> <pre><code>{:name \"deftest\"\n :detail \"deftest clojure.test\"\n :snippet\n \"(deftest ${1:name}-test\n    (testing \\\"${2:Context of the test assertions}\\\"\n      (is (= ${3:assertion-values}))$4))\n  $0\"}\n</code></pre> <p>Create a new assertion group using the <code>clojure.test/testing</code> form.</p> <p>Using <code>testing</code> before an assertion form pull that assertion into the group</p> <pre><code>  {:name \"testing\"\n   :detail \"testing clojure.test\"\n   :snippet \"(testing \\\"${1:description-of-assertion-group}\\\"\\n $0)\"}\n</code></pre> <p>Define an <code>is</code> assertion for a <code>deftest</code></p> <pre><code>  {:name \"is\"\n   :detail \"assertion for clojure.test\"\n   :snippet \"(is (= ${1:function call} ${2:expected result}))$0\"}\n</code></pre>"},{"location":"clojure-editors/clojure-lsp/snippets/","title":"Clojure LSP Snippets","text":"<p>Custom snippets are defined in the Clojure LSP EDN configuration using the <code>:additional-snipets</code> key.  The snippet body uses the same tab stop and placeholder syntax as Yasnipets, although the body is contained within a string.</p> <p>Built-in snippets can include Clojure code for generating the text of the snippet when expanded.  Custom snippets do not currently support evaluation of code in the snippet.</p> Clojure LSP Configuration locations <p>Project specific configuration resides in <code>.lsp/config.edn</code></p> <p>User level configuration is either <code>$XDG_CONFIG_HOME/clojure-lsp/config.edn</code> or <code>$HOME/.clojure-lsp/config</code></p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-definition","title":"Snippet definition","text":"<p>The <code>:additional-snippets</code> key is associated with a vector or hash-maps, <code>[{}{},,,]</code> with each hash-map defining a snippet using the keys:</p> <p><code>:name</code> - name of the snippet, typed into the editor for completion</p> <p><code>:detail</code> - a meaningful description of the snippet</p> <p><code>:snippet</code> - the definition of the snippet, with tab stops and current-form syntax</p> <p>The <code>:snippet</code> can be any text, ideally with syntax that is correct for the particular language</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-tab-stops","title":"Snippet Tab Stops","text":"<p>Include <code>$</code> with a number, e.g. <code>$1</code>,<code>$2</code>,<code>$3</code>,  to include tab stops in the snippet.  Once the snippet code has been generated, <code>TAB</code> key jumps through the tab stops in sequence, allowing customisation of a generic snippet.</p> <p><code>$0</code> marks the final position of the cursor, after which <code>TAB</code> has no more positions in the snippet to jump to.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#snippet-current-form","title":"Snippet current-form","text":"<p>When a Clojure LSP snipped includes <code>$current-form</code> then typing a snippet name in front of an existing Clojure form includes that form in the generated code.</p> <pre><code>{:additional-snippets [{:name \"wrap-let-sexpr\"\n                        :detail \"Wrap current sexpr in let\"\n                        :snippet \"(let [$1 $current-form] $0)\"}]}\n</code></pre> <p>Limited scope with current-form</p> <p>A Snippet including <code>$current-form</code> is only active when typed in front of an existing expression.  A snippet is not recognised when typed at the top level.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#placeholders","title":"Placeholders","text":"<p>Tab Stops can also include default values or text used as hint on what each tab stop value is for.  These are referred to as placeholders.</p> <p><code>${1:default-value}</code> is the form of a placeholder for tab stop 1.  When the cursor tabs to tab stop 1, the default-value text is highlighted and replaces as soon as characters are typed.</p> <p>Placeholder text is not replaced for <code>$0</code> tab-stop, as the snippet interaction is effectively over at this point.</p> <p>The <code>deftest</code> custom snippet shows examples of placeholders for three tab stops.</p> <pre><code>{:name \"deftest\"\n :detail \"deftest clojure.test\"\n :snippet\n \"(deftest ${1:name}-test\n    (testing \\\"${2:Context of the test assertions}\\\"\n      (is (= ${3:assertion-values}))$4))\n  $0\"}\n</code></pre> <p>Escape string quotes in snippet body</p> <p>Use <code>\\</code> character before the <code>\"</code> character within the snippet body.  For example, doc-strings in <code>defn</code> function definitions or the string in <code>testing</code> function.</p>"},{"location":"clojure-editors/clojure-lsp/snippets/#code-driven-snippet","title":"Code driven snippet","text":"<p>The built-in <code>defn</code> snippet uses Clojure code to help generate the snippet.</p> <p><code>%s</code> is a substitution point within a snippet, used by the standard Clojure <code>format</code> command, used to included either <code>defn ^:private</code> or <code>defn-</code>, depending on the value returned from the <code>if</code> expression.</p> <p><code>:use-metadata-for-privacy?</code> is a key from the Clojure LSP configuration</p> <pre><code> {:label \"defn-\"\n  :detail \"Create private function\"\n  :insert-text (format \"(defn%s ${1:name} [$2]\\n  ${0:body})\"\n                       (if (:use-metadata-for-privacy? settings)\n                         \" ^:private\"\n                         \"-\"))}\n</code></pre> <p>The syntax for built-in snippets is slightly different that the <code>:additional-syntax</code> form.  The internal form uses <code>:label</code> for <code>:name</code> and <code>:insert-text</code> for <code>:snippet</code>.</p> <p>Code supported only in built-in snippets</p> <p>Clojure code only works for built-in snippets and not for <code>:additional-snippets</code>.</p> <p>Clojure LSP is compiled by Graal to a native binary, including the built-in snippets.  To include Clojure code in a snippet then consider submitting a pull request to the Clojure LSP project to add a built-in snippet.</p>"},{"location":"clojure-spec/","title":"Clojure Specifications","text":"<p>Clojure Spec is a library for defining specifications around data and functions to test for correctness.</p> <p>A spec defines the expected shape of specific values in Clojure and specs are intended to be used across multiple projects.  Specifications for more complex values are composed of specific value specifications, providing a flexible way to define what key parts of the system should look like.</p> <p>Clojure specs are used to generate comprehensive test data, identifying more scenarios and edge cases with less code.</p> <p>Spec is included in Clojure version 1.9 onward and can be used by requiring the <code>clojure.spec.alpha</code> in the REPL or in namespaces of a Clojure project.</p>"},{"location":"clojure-spec/#recommended-reading","title":"Recommended Reading","text":"<p>What is Clojure spec - an illustrated guide</p>"},{"location":"clojure-spec/#purpose-of-clojure-spec","title":"Purpose of Clojure spec","text":"<p>A summary highlighting the common purposes that Clojure Spec is used for</p> Purpose Description Living documentation Use spec to include specifications in Function documentation (<code>fdef</code>) Data Validation Ensure the data entering and leaving the system or its key functions are of the correct form Test Data Generation Provide extensive test data coverage with minimal code maintenance Generative testing of functions Test functions using their spec defined contract (<code>fdef</code>) Generative scenario testing Specific correct usage paths for known states Development time checking Instrument functions to ensure correctness Derive code from specifications Specify a system of record for data structures, internal and external to the system."},{"location":"clojure-spec/#example-use-cases","title":"Example use cases","text":"<ul> <li>API requests (schema is often used here, but so can spec)</li> <li>Checking data pulled from / pushed to message systems (e.g. Kafka, TIBCO)</li> <li>Data specifications (eg. Vega-lite)</li> </ul>"},{"location":"clojure-spec/#example-code","title":"Example code","text":"<p> practicalli/leveraging-spec</p> <p>practicalli/leveraging-spec - basic examples of using spec, following the Practicalli Spec broadcasts</p>"},{"location":"clojure-spec/#understanding-the-basics-of-clojure-spec","title":"Understanding the basics of Clojure Spec","text":""},{"location":"clojure-spec/#trying-clojurespec","title":"Trying clojure.spec","text":"<p>Follow the examples in these two excellent videos</p> <p> </p> <p> </p>"},{"location":"clojure-spec/#why-is-the-spec-library-called-alpha","title":"Why is the spec library called alpha?","text":"<p>The library is called <code>clojure.spec.alpha</code> as the design of spec is still evolving and there may be some changes to the design in later versions.  Clojure aims for backwards compatibility, so new versions typically do not break existing use of libraries.</p> <p>There are some important changes being developed for spec version 2 and a few things may change, however, the large majority of Spec will remain the same and is safe to use.</p>"},{"location":"clojure-spec/#references","title":"References","text":"<p>spec guide - clojure.org Introducing clojure.spec clojure.spec - rational and overview</p> <p>spec.alpha API reference</p> <p>How do you use clojure.spec - Sean Corfield</p> <p> Specifications for <code>clojure.core</code></p> <p> Leveraging clojure.spec - Stuart Halloway  spec.test - Stuart Halloway</p> <p>Clojure Spec: Expressing Data Constraints without Types</p>"},{"location":"clojure-spec/add-spec-to-projects/","title":"Add Spec to a project","text":"<p>Create a new project or clone  practicalli/leveraging-spec which includes several examples of using Clojure Spec.</p> Create new projectClone Practicalli Leveraging Spec project <p>Create a new Clojure CLI project using the  Practicalli project templates </p> Create new project<pre><code>clojure -T:project/create :template practicalli/minimal :name practicalli/leveraging-spec\n</code></pre>  Practicalli Clojure CLI Config - :project/create alias <p> Practicalli Clojure CLI Config repository includes the <code>:project/create</code> alias for creating new Clojure projects from a template using <code>deps-new</code>.</p> <p>The project is created with Clojure as a dependency, which includes the <code>clojure.spec.alpha</code> library.</p> <p>Clojure 1.9.0 or higher versions include Clojure Spec.  Clojure 1.11.1 is recommended.</p> <p> practicalli/leveraging-spec project includes Clojure Spec examples for values and functional arguments, along with unit tests using clojure spect-test.</p> <pre><code>https://github.com/practicalli/leveraging-spec.git\n</code></pre>"},{"location":"clojure-spec/add-spec-to-projects/#project-dependencies","title":"Project Dependencies","text":"<p>Clojure Spec is included in Clojure so only <code>org.clojure/clojure</code> dependency is required in the <code>deps.edn</code> file for the project.</p> <p>Clojure project dependency</p> deps.edn<pre><code>{:paths [\"src\" \"resources\"]\n :deps {org.clojure/clojure {:mvn/version \"1.11.1\"}}}\n</code></pre>"},{"location":"clojure-spec/add-spec-to-projects/#use-spec-in-namespace","title":"Use spec in namespace","text":"<p>Require the <code>clojure.spec.alpha</code> namespace in the <code>ns</code> definition using the <code>spec</code> alias name.  Practicalli recommends using <code>spec</code> (rather than <code>s</code> as it is much clearer as to where the functions are defined)</p> <p>Clojure project dependency</p> <pre><code>(ns practicalli.leveraging-spec\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>Evaluate the namespace definition to start using the functions from the namespace.</p> <p></p> <p>All functions from <code>clojure.spec.alpha</code> are now accessible using the <code>spec</code> alias, e.g. <code>spec/conform</code>, <code>spec/valid?</code>, <code>spec/def</code>.</p>"},{"location":"clojure-spec/add-spec-to-projects/#testing-with-spec","title":"Testing with spec","text":"<p>Add the <code>clojure.spec.test.alpha</code> using the <code>spec-test</code> alias, along with <code>clojure.spec.test.alpha</code> as <code>spec</code> alias</p> <p>Clojure project dependency</p> src/practicalli/leveraging_spec.clj<pre><code>(ns practicalli.leveraging-spec\n  (:require\n    [clojure.spec.alpha :as spec]\n    [clojure.spec.test.alpha :as spec-test]))\n</code></pre>"},{"location":"clojure-spec/organising-specs/","title":"Organizing Specifications","text":"<p>Data and function definition specifications are typically placed in a dedicated <code>specification</code> namespaces, e.g <code>src/domain/project/specification.clj</code>.  </p> <p>Add the data specifications (<code>spec/def</code>), custom predicate functions and function specifications (<code>spec/fdef</code>) to the <code>specifications</code> namespace.</p> <p>Specifications for an architecture layer can be organised next to the namespaces managing the layer, e.g. database. </p> <p>Migrate specifications to a library once they are applicable to multiple projects.</p>"},{"location":"clojure-spec/organising-specs/#instrumenting-functions","title":"Instrumenting functions","text":"<p>Add <code>spec-test/instrument</code> expressions to the <code>specifications</code> file, after the <code>spec/fdef</code> expressions.</p> <p>Rather than create individual expressions, create a <code>clojure.core/def</code> to contain a collection of all the <code>spec/fdef</code> expressions.  This list can then be used to <code>instrument</code> and <code>unstrument</code> all the <code>spec/fdef</code> specifications.</p> <pre><code>(def ^:private function-specifications\n  [`card-game/deal-cards\n   `card-game/winning-player])\n</code></pre> <p>Write simple helper functions to wrap the instrumenting of function specifications</p> <pre><code>(defn instrument-all-functions\n  []\n  (spec-test/instrument function-specifications))\n\n(defn unstrument-all-functions\n  []\n  (spec-test/unstrument function-specifications))\n</code></pre>"},{"location":"clojure-spec/organising-specs/#unit-testing","title":"Unit testing","text":"<p>Specifications can be incorporated into the existing unit tests, so it is sensible to keep them under the corresponding <code>test</code> directory files.</p>"},{"location":"clojure-spec/organising-specs/#generative-testing","title":"Generative testing","text":"<p>Using <code>spec-test/check</code> will generate 1000 data values for each expression, so by default these tests will take far longer that other tests.</p> <p>Configuring generative tests to only generate a small number of values will make <code>spec-test/check</code> expressions return almost instantaneously.  In this example, only 10 data values are generated</p> <pre><code>(spec-test/check `deal-cards\n                   {:clojure.spec.test.check/opts {:num-tests 10}})\n</code></pre> <p>Generative testing with small generators can be run regularly during development without impacting fast feedback.</p> <p> Testing with Clojure Spec </p>"},{"location":"clojure-spec/using-spec-in-the-repl/","title":"REPL Experiments with Clojure Spec","text":"Create a minimal Project <p>Clojure Spec can be tried without creating a Clojure project, although creating a project is useful if saving the Clojure Spec code experiments.</p> <p>Create a minimal Clojure project with a Clojure CLI deps.edn configuration. <pre><code>clojure -T:project/create :template practicalli/minimal :name practicalli/spec-experiments\n</code></pre></p> <p>Run a Clojure REPL with a rich terminal UI</p> REPL RebelREPL Reloaded <p>A REPL with a rich terminal UI <pre><code>clojure -M:repl/rebel\n</code></pre></p> <p>A REPL with a rich terminal UI and tools to support the Practicalli REPL Reloaded workflow. <pre><code>clojure -M:repl/reloaded\n</code></pre></p> <p>Require the <code>clojure.spec.alpha</code> using an alias called <code>spec</code> to use functions from that namespace.</p> <pre><code>(require '[clojure.spec.alpha :as spec])\n</code></pre> <p>NOTE: <code>clojure.spec.alpha</code> is often aliased as <code>s</code>, although  Practicalli avoids</p>"},{"location":"clojure-spec/using-spec-in-the-repl/#spec-auto-completion","title":"Spec auto-completion","text":"<p>Using rebel-readline for the Clojure REPL will show autocompletion for all spec functions once the spec namespace has been required.</p> <p>Type <code>(spec /</code> and press <code>TAB</code> to list all the functions in the namespace.</p> <p> </p> <p>Typing a space character after the full name of a function shows the function signature with arguments that should be passed to that function.</p> <p> </p> <p>Ctrl x Ctrl d displays the documentation for the current function </p> <p> </p> <p> </p>"},{"location":"clojure-spec/using-spec-in-the-repl/#check-data-conforms-to-specification","title":"Check data conforms to specification","text":"<p>Use the <code>spec/conform</code> and <code>spec/valid?</code> functions to test if data matches a specification.  In these examples, predicate functions are used as a specification.</p> <p> </p>"},{"location":"clojure-spec/using-spec-in-the-repl/#example-expressions","title":"Example expressions","text":"<p><code>spec/conform</code> will return the value if it conforms to the specification, or <code>:clojure.spec.alpha/invalid</code> if the data does not conform.</p> <p>Clojure Spec - Conform values</p> <pre><code>(spec/conform odd? 101)\n\n(spec/conform integer? 1)\n\n(spec/conform seq? [1 2 3])\n\n(spec/conform seq? (range 10))\n\n(spec/conform map? {})\n\n(spec/conform map? (hash-map :a 1 :b 2))\n</code></pre> <p><code>spec/valid?</code> returns true or false</p> <p>Clojure Spec - validate values</p> <pre><code>(spec/valid? even? 180)\n\n(spec/valid? string? \"Am I a valid string\")\n\n(spec/valid? (fn [value] (&gt; value 10000)) 30076)\n\n(spec/valid? #(&gt; % 10000) 30076)\n\n(spec/conform #(&gt; % 10000) 30076)\n</code></pre>"},{"location":"clojure-spec/data/","title":"Clojure Spec for data","text":"<p>Specifications can be defined for any data in Clojure, be that simple values or complex data structures. More complex specifications are composed of individual specifications, providing a flexible way to define specifications without building a brittle hierarchy.</p>"},{"location":"clojure-spec/data/#what-is-a-specification","title":"What is a specification","text":"<p>Specifications can be predicates (return true or false), literal values in sets and entity maps.</p> <p>There are many predicate functions that come with Clojure which help speed the creation of specifications.  Clojure function definitions (<code>fn</code>, <code>defn</code>) can be used to define custom predicate functions too.</p>"},{"location":"clojure-spec/data/#do-values-meet-a-specification","title":"Do values meet a specification","text":"<p>The functions use to compare data with a specification are:</p> <ul> <li><code>conform</code> - test if data conforms to a specification, returning the conformed value</li> <li><code>valid?</code> - predicate to test if data conforms to a specification, returning true of false</li> <li><code>explain</code> - explain why a value is not conforming to a specification</li> </ul> <p>There are variations on explain, that present the results in different formats.</p>"},{"location":"clojure-spec/data/#workflow-for-data-specifications","title":"Workflow for data specifications","text":"<p>Using Clojure Specification is very flexible, they can be used as much or as little as required.</p> <p>Typically Specifications are created when data structures are being modeled, which can be done via experimenting in the REPL or taking a test first approach.  Either way is viable.</p> <p>The generative tests section shows how specifications are used to generate mock data, so creating specifications earlier on in the development process will provide a wider range of data for unit tests and repl experimentation.</p> <p>Spec and nil values</p> <p>Some predicates do not consider <code>nil</code> as a valid value, espcially those predicates that check for a specific type</p> <p><code>spec/nilable</code> will transform a predicate to use nil</p> <pre><code>(spec/valid? string? nil)\n\n(type \"what type am I\")\n(type nil)\n\n(spec/valid? (spec/nilable string?) nil)\n</code></pre>"},{"location":"clojure-spec/data/and-or-specifications/","title":"Combining specifications with and and or","text":"<p><code>clojure.core/and</code> function and <code>clojure.core/or</code> function can be used to define a specification with multiple parts.</p>"},{"location":"clojure-spec/data/and-or-specifications/#conform-to-one-or-more-specifications","title":"Conform to One or more specifications","text":"<p>A specification for residential address included either a house number or name.  The <code>clojure.core/or</code> function allows either type of value to be used and conform to the specification.</p> <pre><code>(spec/def ::house-name-number (or string? int?))\n</code></pre> <p>Using <code>spec/or</code> then unique keys are required for each possible type of value.  Keys are used to explain where a failure occurred if values do not conform to the specification.</p> <pre><code>(spec/def ::house-name-number (spec/or :string string?\n                                       :number int?))\n</code></pre> <p>If specifications are uses as the options in the <code>clojure.spec.alpha/or</code> then those specification names are used as the keys to explain where failure to conform to the specification happened.</p> <pre><code>(spec/def ::social-security-id (spec/or ::social-security-id-uk\n                                        ::social-security-id-usa))\n</code></pre>"},{"location":"clojure-spec/data/and-or-specifications/#conform-to-all-specifications","title":"Conform to all specifications","text":"<p>Create a composite specification using <code>clojure.spec.alpha/and</code> when all specifications should be conformed by the values</p> <p>For an arranged banking overdraft limit, the value should be a positive number, that is an integer type and is less than 1000.</p> <pre><code>(spec/def ::arranged-overdraft-limit (spec/and pos? int? #(&gt; 1000 %)))\n</code></pre> <p>If a value does not conform to any of the three specifications then the value fails the <code>::arranged-overdraft-limit</code> specification.</p>"},{"location":"clojure-spec/data/composite-specifications/","title":"Composing Specifications","text":"<p>No spec is an island</p> <p>Composing individual specifications is an effective way to build larger abstractions in specifications without creating fixed hierarchical structures that are harder to refactor.</p> <p>Require specification namespace to the page</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p><code>spec/and</code> is used when all specifications should be true.</p> <pre><code>(spec/def ::meaning-of-life\n  (spec/and int?\n            even?\n            #(= 42 %)))\n</code></pre> <p><code>spec/or</code> is use when one or more specifications should be true</p> <pre><code>(spec/def ::meaning-of-life-int-or-string\n  (spec/or :integer #(= 42 %)\n           :string  #(= \"forty two\" %)))\n</code></pre> <p>Each condition in the spec is annotated with a label for each conditional branches.</p> <p>Labels are included in the return result from <code>spec/explain</code> when values do not conform to a specification, providing context as to why a value failed the specification.</p> <p>When an or is conformed, it returns a vector with the condition name and conformed value.</p> <pre><code>(spec/conform ::meaning-of-life-int-or-string 42)\n</code></pre> <pre><code>(spec/conform ::meaning-of-life-int-or-string \"forty two\")\n</code></pre> <pre><code>(spec/conform ::meaning-of-life-int-or-string :entropy)\n</code></pre> <pre><code>(spec/explain ::meaning-of-life-int-or-string :entropy)\n</code></pre>"},{"location":"clojure-spec/data/composite-specifications/#individual-specifications","title":"Individual specifications","text":"<p>Before composing a more abstract specification, first define individual specifications</p> <pre><code>(spec/def ::first-name string?)\n</code></pre> <pre><code>(spec/def ::last-name string?)\n</code></pre> <pre><code>(spec/def ::residential-address string?)\n</code></pre>"},{"location":"clojure-spec/data/composite-specifications/#composing-hash-map-specification","title":"Composing hash-map specification","text":"<p>The individual specifications can now be composed into a single specification.</p> <p><code>keys</code> function combines specifications to form a composite specification in the form of a Clojure hash-map.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::residential-address]))\n</code></pre> <p>Use the composite specification with a value</p> <pre><code>(spec/conform ::customer-details\n  {::first-name \"Jenny\"\n   ::last-name \"Jetpack\"\n   ::residential-address \"42 meaning of life street, Earth\"})\n</code></pre>"},{"location":"clojure-spec/data/conform/","title":"Conform","text":""},{"location":"clojure-spec/data/conform/#does-a-value-conform-to-a-specification","title":"Does a value conform to a specification?","text":"<p><code>clojure.spec.alpha/conform</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>:clojure.spec.alpha/invalid</code> is returned when a value does not conform to a specification.</p> <p>If the value does conform to the specification, then the value is returned.  This value is referred to as a conformed value.</p>"},{"location":"clojure-spec/data/conform/#require-the-clojure-spec-library","title":"Require the Clojure spec library","text":"<p>Set the namespace for the page and require clojure.spec.alpha library, setting the alias to <code>spec</code></p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/conform/#using-conform","title":"Using conform","text":"<p>If the value conforms to the spec, a conformed value is returned</p> <pre><code>(spec/conform odd? 101)\n</code></pre> <p>When a value does not conform to a spec, the value <code>:clojure.spec.alpha/invalid</code> is returned</p> <p><pre><code>(spec/conform even? 101)\n</code></pre> </p> <p><pre><code>(spec/conform integer? 1)\n</code></pre> </p> <p><pre><code>(spec/conform seq? [1 2 3])\n</code></pre> </p> <p><pre><code>(spec/conform seq? (range 10))\n</code></pre> </p> <p><pre><code>(spec/conform map? {})\n</code></pre> </p> <p><pre><code>(spec/conform map? (hash-map :a 1 :b 2))\n</code></pre> </p>"},{"location":"clojure-spec/data/defining-specifications/","title":"Defining specifications","text":"<p><code>clojure.spec.alpha/def</code> binds a name to a specification, just like <code>clojure.core/def</code> binds a name to a value.</p> <p>Binding a name means specifications are available throughout the code and in other projects if the project is included as a library.</p>"},{"location":"clojure-spec/data/defining-specifications/#naming-fully-qualified-keywords","title":"Naming - fully qualified keywords","text":"<p>Specification names should use fully qualified keywords, typically using the namespace in which the specification is defined in.</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <pre><code>(spec/def :practicalli.clojure.specifications/number number?)\n</code></pre>"},{"location":"clojure-spec/data/defining-specifications/#auto-resolve-macro","title":"auto-resolve macro","text":"<p><code>::</code> double colon is the auto-resolve macro, which will pre-pend the current namespace to the specification keyword. The <code>::</code> notation removes the need to edit fully qualified names should a specification be moved to a different namespace.</p> <pre><code>(spec/def ::number number?)\n</code></pre> <p>Fully Qualified keywords</p> <p>Using fully qualified keywords ensures they are unique and therefore can be used across all projects.</p> <p>Namespaces are usually unique as they include the name of the company or organization behind the code and any project or component names used to organize the code.</p>"},{"location":"clojure-spec/data/entity-maps/","title":"Entity maps","text":"<p>An entity map is a Specification for a Clojure hash-map of key-value pairs.</p> <p>A hash-map is a very effective way to express information in Clojure.  The key should be a descriptive label to express meaning of the value it is associated with.  Without the keys describing the meaning, it is harder for a developer to understand the data.</p> <pre><code>{:account-id 12345 :user-name \"jenny1999\" :name \"Jenny Jetpack\" :address \"42 Meaning place, Earth\" :social-security \"ABC-123-45-6789\"}\n</code></pre> <p>A hash-map contains any number of key-value pairs, keys are used for efficient lookup so there is no concern over ordering.  Passing a hash-map as an argument to a function reduces refactoring required as the signature of the function remains the same and functions can be selective as to which key-value pairs they use.</p> <p>For these reasons, hash-maps are a very common data structure to pass data between functions.</p>"},{"location":"clojure-spec/data/entity-maps/#defining-entity-maps","title":"Defining entity maps","text":"<p>The Clojure Spec <code>keys</code> function is used to create a specification for a hash-map of key-value pairs.</p> <p><code>keys</code> creates a specification from required keys, <code>:req</code>, and optional keys <code>:opt</code>.</p> <p>To define the specification for a player in an online game, first the individual specifications that make up the player hash-map are created.</p> <pre><code>(spec/def ::account-id uuid?)\n(spec/def ::name string?)\n(spec/def ::score int?)\n(spec/def ::profile string?)\n(spec/def ::games-played #{:vectron :utrazap :avakato})\n</code></pre> <p>Those specifications are composed together to create a specification for the player</p> <pre><code>(spec/def\n  ::player-account\n  (spec/keys :req [::account-id ::name ::score]\n             :opt [::profile ::games-played]))\n</code></pre> <p>For a hash-map to meet the <code>::player-account</code> specification it must contain the <code>:req</code> keys with values that conform to the individual specifications.  The hash-map can also include any key-value pairs that conform to the <code>:opt</code> specifications.</p> <p>If any keys are in the map that do not appear in either <code>:req</code> or <code>:opt</code> then that hash-map does not conform to the <code>::player-account</code> specification.</p>"},{"location":"clojure-spec/data/entity-maps/#example-covid19-dashboard","title":"Example: covid19-dashboard","text":"<p>The <code>coronavirus-cases-data</code> function takes a hash-map of values to make that function easier to extend without breaking existing calls</p> <p>Default values can be used if no value is passed as an argument. Extra values can be ignored without breaking the code.</p> <p>Coronavirus Cases Specification</p> <pre><code>(defn fun-name\n  [csv location date])\n\n(defn coronavirus-cases-data\n  \"Extract and transform cases data for specific locations and date\"\n  [{:keys [csv-file locations date]}]\n  #_(-&gt; (extract-data-from-csv csv-file)\n        (data-set-remove-locations locations)\n        (data-set-specific-date date)))\n\n(coronavirus-cases-data\n  {:csv-file  \"data-sets/uk-coronavirus-cases.csv\"\n   :locations #{\"Nation\" \"Country\" \"Region\"}\n   :date      \"2020-04-30\"})\n\n;; Define the individual keys for the hash-map\n(spec/def ::csv-file string?)\n(spec/def ::locations set?)\n(spec/def ::date string?)\n\n(spec/def ::cases-data\n  (spec/keys :req [::csv-file ::locations ::date]))\n</code></pre>"},{"location":"clojure-spec/data/explain/","title":"Explaining non-conforming values","text":"<p><code>clojure.spec.alpha/explain</code> describes why a value does not satisfy a specification.</p> <p><code>clojure.spec.alpha/explain</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>Success</code> string is sent to standard out if the value meets the specification</p> <p>A string explaining where the value deviates from the specification is sent to standard out if the value does not meet the specification.</p> <p>There are several variations on the explain function for different situations</p> <ul> <li><code>explain</code> - sends the return value to the standard out / REPL</li> <li><code>explain-str</code> - returns a human readable result.</li> <li><code>explain-data</code> - returns a data structure of the error to be processed by other code</li> </ul>"},{"location":"clojure-spec/data/explain/#example-of-a-failing-value","title":"Example of a failing value","text":"<p>First define a namespace and require the Clojure Spec namespace</p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n\n(spec/def ::meaning-of-life #(= 42 %))\n</code></pre> <p>Given the following specification</p> <pre><code>(spec/explain ::meaning-of-life 24)\n</code></pre> <p>Using the value <code>24</code> with that specification will fail.  Using explain we can see why</p> <pre><code>(spec/def ::meaning-of-life-int-or-string\n  (spec/or :integer #(= 42 %)\n           :string  #(= \"forty two\" %)))\n</code></pre> <p>In this case explain returned the</p> <ul> <li>value being checked against the spec</li> <li>result of that check (failed)</li> <li>predicate used to check the value</li> <li>spec name used to check the value</li> </ul> <p>Notice that the value failed on the first condition, <code>:integer</code>, then stopped without checking the second, <code>:string</code>. The <code>spec/and</code> macro works the same as <code>clojure.core/and</code> in that is stops as soon as something fails.</p> <pre><code>(spec/explain ::meaning-of-life-int-or-string 24)\n</code></pre> <p>In this case we still have the value checked, the result and the predicate More information is provided as to where in the spec the value failed <code>:at</code> shows the path in the spec where the failure occurred, very useful for nested structures This shows the value of naming your specs descriptively</p>"},{"location":"clojure-spec/data/explain/#explain-with-a-string","title":"Explain with a string","text":"<p>rather than send information to the system out</p> <pre><code>(spec/explain-str ::meaning-of-life 24)\n</code></pre> <pre><code>(spec/explain-data ::meaning-of-life 24)\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/","title":"Hierarchical Specifications","text":"<p>Defining specifications for data that is hierarchical or nested in nature.</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#example-hierarchical-data","title":"Example hierarchical data","text":"<pre><code>{:top-level-key {:nested-key \"value\"}}\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#individual-specifications","title":"Individual specifications","text":"<pre><code>(spec/def ::first-name string?)\n</code></pre> <pre><code>(spec/def ::last-name string?)\n</code></pre> <pre><code>(spec/def ::residential-address string?)\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#composite-specification","title":"Composite Specification","text":"<p><code>keys</code> function combines specifications to form a composite specification in the form of a Clojure hash-map.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::residential-address]))\n</code></pre>"},{"location":"clojure-spec/data/hierarchical-specifications/#hierarchical-specification","title":"Hierarchical Specification","text":"<p>A user account is composed of a user-id and customer details.  Rather than include the individual customer details, the composite customer-details specification.</p> <p>The <code>::user-id</code> specification is as follows</p> <pre><code>(spec/def ::user-id uuid?)\n</code></pre> <p>The <code>::user-account</code> specification</p> <pre><code>(spec/def ::user-account\n  (spec/keys\n    :req [::user-id ::customer-details]))\n</code></pre> <p>The following data structure will conform to the specification</p> <pre><code>{::user-id #uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\"\n ::customer-details {::first-name \"Jenny\"\n                     ::last-name \"Jetpack\"\n                     ::residential-address \"Earth\"}}\n</code></pre>"},{"location":"clojure-spec/data/literal-values/","title":"Literal values","text":"<p>Sets can be used as predicate functions returning true if the value is within the set</p> <p>Checking valid playing cards</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <pre><code>(spec/valid? #{:club :diamond :heart :spade} :club)\n</code></pre> <pre><code>(spec/valid? #{:club :diamond :heart :spade} 42)\n</code></pre> <p>Answer to the ultimate question?</p> <pre><code>(spec/valid? #{42} 42)\n</code></pre> <p>Using sets for literal values is similar to using the <code>clojure.core/contains?</code> function with a set collection type.</p> <pre><code>(contains? #{:clubs :diamonds :hearts :spades} :hearts )\n</code></pre>"},{"location":"clojure-spec/data/map-literals/","title":"Map literal syntax - <code>#:</code> and <code>#::</code>","text":"<p><code>#:</code> map literal macro for Clojure hash-maps adds a given namespace to all the keywords contained in the hash-map.</p> <p><code>#::</code> map literal macro for keyword auto-resolve adds the current fully qualified namespace to all the keywords in the hash-map</p>"},{"location":"clojure-spec/data/map-literals/#require-clojure-spec-in-the-namespace-definition","title":"Require clojure spec in the namespace definition","text":"<pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>In this example the keys in the map are unqualified.</p> <pre><code>{:simplifying      []\n    :keyword-names    []\n    :with-autoresolve []\n    :map-literal      []}\n</code></pre>"},{"location":"clojure-spec/data/map-literals/#qualifying-keys-with-auto-resolve","title":"Qualifying keys with auto-resolve","text":"<p>Using the map literal macro for auto-resolve instructs Clojure to treat all keys in the map as qualified to the current namespace</p> <p>The following hash-map has the map literal macro.</p> <pre><code>#::{:simplifying      []\n    :keyword-names    []\n    :with-autoresolve []\n    :map-literal      []}\n</code></pre> <p>This is the same as explicitly writing out the fully qualified domain for each key in the map.</p> <p>However, if we move the map to another namespace, then the explicit namespaces would need to be updated.</p> <pre><code>{:practicalli.clojure/simplifying      []\n :practicalli.clojure/keyword-names    []\n :practicalli.clojure/with-autoresolve []\n :practicalli.clojure/map-literal      []}\n</code></pre>"},{"location":"clojure-spec/data/map-literals/#qualifying-keywords-with-a-specific-name","title":"Qualifying keywords with a specific name","text":"<p>Rather than take the name from the current namespace, an explicit name can be added to all the keys in the map</p> <pre><code>#:practicalli.naming {:simplifying      []\n                      :keyword-names    []\n                      :with-autoresolve []\n                      :map-literal      []}\n</code></pre> <p>This is the same as explicitly writing that name in front of each of the keywords in the map.</p> <pre><code># {:practicalli.naming/simplifying      []\n   :practicalli.naming/keyword-names    []\n   :practicalli.naming/with-autoresolve []\n   :practicalli.naming/map-literal      []}\n</code></pre> <p>Map literals are relevant to Entity maps with spec.</p>"},{"location":"clojure-spec/data/predicate-functions/","title":"Spec - Predicate functions","text":"<p>A predicate is a function that returns a true or false value and their names end with <code>?</code> by convention.</p> <pre><code>(odd? 1)\n</code></pre> <pre><code>(string? \"am i a string\")\n</code></pre> <pre><code>(int? 2.3)\n</code></pre> <pre><code>(int? 2.3)\n</code></pre> <p><code>clojure.core</code> predicate functions</p> <p><code>clojure.core</code> defines 80+ predicate functions</p>"},{"location":"clojure-spec/data/predicate-functions/#predicate-functions-in-specs","title":"Predicate functions in specs","text":"<p>Predicate functions can be used as un-named specifications to test values conform.</p> <p>Include the <code>clojure.spec.alpha</code> namespace to access the spec functions.</p> <pre><code>(require '[clojure.spec.alpha :as spec])\n</code></pre> <pre><code>(spec/conform int? 42)\n</code></pre> <pre><code>(spec/conform seq? (range 4))\n</code></pre>"},{"location":"clojure-spec/data/predicate-functions/#custom-predicate-functions","title":"Custom predicate functions","text":"<p>Define custom predicate functions with <code>defn</code> or <code>fn</code> or the short form <code>#()</code></p> <p>Using an anonymous function</p> <pre><code>(spec/conform (fn [value] (= value 42)) 42)\n</code></pre> <p>When the expression is quite terse, then the short form of an anonymous function is typically used.  The <code>%</code> represents the value passed as an argument.</p> <pre><code>(spec/conform #(= % 42) 42)\n</code></pre>"},{"location":"clojure-spec/data/registry/","title":"Registry for unique and re-usable specifications","text":"<p>So far we have just use predicate functions directly in the code examples.</p> <p>Using a registry, specs can be uniquely defined across the whole project. Defining a spec gives that spec a name that has a fully qualified namespace</p> <p>Use the spec specific <code>def</code> function to bind a new spec name and fully qualified namespace and place it in the registry</p> <pre><code>(spec/def :playing-card/suit  #{:club :diamond :heart :spade} )\n</code></pre> <pre><code>(spec/conform :playing-card/suit :diamond)\n</code></pre> <pre><code>(spec/def :show-cats/cat-bread #{:abyssinian :birman :chartreau :devon-rex\n                        :domestic-short-hair :domestic-long-hair})\n</code></pre>"},{"location":"clojure-spec/data/registry/#removing-specs-from-the-registry","title":"Removing specs from the registry","text":"<p>Named specifications can be removed from the registry by binding the name to <code>nil</code>.</p> <p>If specification names are to be refactored, then the original name should be set to <code>nil</code> and evaluated, before changing the name.  This will ensure stale specifications are not residing in the REPL.</p> <p>Here is a named specification as an example</p> <pre><code>(spec/def ::unwanted #{:abandoned})\n</code></pre> <p>The specification is evaluated in the REPL (above) and currently works.</p> <pre><code>(spec/conform ::unwanted :abandoned)\n</code></pre> <p>Remove this specification from the registry by binding it to nil</p> <pre><code>(spec/def ::unwanted nil)\n</code></pre> <p>Now the specification is unavailable</p> <pre><code>(spec/conform ::unwanted :abandoned)\n</code></pre> <p>Registry not persistent</p> <p>Restarting the REPL will loose all specification names in the registry as it is not persistent across REPL sessions.</p>"},{"location":"clojure-spec/data/valid-q/","title":"Is the value valid?","text":"<p><code>clojure.spec.alpha/valid?</code> takes two arguments</p> <ul> <li>a specification</li> <li>a value to test against the specification</li> </ul> <p><code>clojure.spec.alpha/valid?</code> is a predicate function.</p> <p><code>true</code> is returned if the value meets the specification, otherwise <code>false</code> is returned.</p>"},{"location":"clojure-spec/data/valid-q/#require-the-clojure-spec-library","title":"Require the Clojure spec library","text":"<p>Set the namespace for the page and require clojure.spec.alpha library, setting the alias to <code>spec</code></p> <pre><code>(ns practicalli.clojure.specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/data/valid-q/#using-valid","title":"Using valid?","text":"<p>If the value is valid then a boolean true is returned.  Experiment with different values and predicate functions.</p> <p><pre><code>(spec/valid? even? 180)\n</code></pre> </p> <p><pre><code>(spec/valid? string? \"Am I a valid string\")\n</code></pre> </p>"},{"location":"clojure-spec/data/valid-q/#using-custom-predicate-functions","title":"using custom predicate functions","text":"<p>Create <code>fn</code> definitions to use as predicate functions.  Any function that returns true or false can be used.</p> <pre><code>(spec/valid? (fn [value] (&gt; value 1024)) 8080)\n</code></pre> <p>The custom predicate function may also be written in the shorter form of a <code>fn</code> definition</p> <pre><code>(spec/valid? #(&gt; % 1024) 8080)\n</code></pre> <p>Use <code>def</code> to bind names to custom predicate functions if they are used more than once in the code base.</p> <p>In this example a name is bound to a function that checks if a port is within the range of IANA registered networking ports.</p> <pre><code>(def registered-port-range?\n  \"Network port number within IANA registered port range\"\n  #(and (&gt; % 1024) #(&lt; % 49151) )\n\n(spec/valid? registered-port-range? 8080)\n</code></pre>"},{"location":"clojure-spec/functions/","title":"Specification for function definitions","text":"<p>Define specifications for your custom functions</p> <ul> <li>Additional documentation - argument and return values and the relationship between them.</li> <li>Instrumenting functions - checking for correct argument values</li> <li>Generative testing - using argument specifications to generate comprehensive test data.</li> </ul> <p>Many of the functions in <code>clojure.core</code> have specifications in the latest version of Clojure.  The specifications for clojure.core functions can be found in the clojure/core.specs.alpha repository on GitHub.</p>"},{"location":"clojure-spec/functions/#clojurecore-examples","title":"clojure.core examples","text":"<p>Specifications used for the <code>defn</code>, <code>defn-</code>, <code>fn</code> functions in <code>clojure.core</code></p> <p>clojure.core specification examples</p> <pre><code>(s/def ::param-list\n  (s/and\n    vector?\n    (s/cat :params (s/* ::binding-form)\n           :var-params (s/? (s/cat :ampersand #{'&amp;} :var-form ::binding-form)))))\n\n(s/def ::params+body\n  (s/cat :params ::param-list\n         :body (s/alt :prepost+body (s/cat :prepost map?\n                                           :body (s/+ any?))\n                      :body (s/* any?))))\n\n(s/def ::defn-args\n  (s/cat :fn-name simple-symbol?\n         :docstring (s/? string?)\n         :meta (s/? map?)\n         :fn-tail (s/alt :arity-1 ::params+body\n                         :arity-n (s/cat :bodies (s/+ (s/spec ::params+body))\n                                         :attr-map (s/? map?)))))\n</code></pre>"},{"location":"clojure-spec/functions/documentation/","title":"Documentation","text":"<p>The Clojure <code>doc</code> function shows the doc string included in a function definition, eg. <code>defn</code> expressions.</p> <p>When a specification is defined for a function using <code>fdef</code> the specification is included in the output of the Clojure <code>doc</code> function.</p> <p>Including specification details clarifies the precise way to use the function and the information it expects.  When a function has a specification the doc string for that function can focus on the purpose of the function rather than the specific types of data used, as that is covered by the function specification.</p>"},{"location":"clojure-spec/functions/documentation/#example","title":"Example","text":"<pre><code>(clojure.repl/doc ::rank)\n\n;; :practicalli.card-game-specifications/rank\n;; Spec\n;;   (into #{:king :queen :ace :jack} (range 2 11))\n</code></pre> <p>When adding a specification to a function definition, <code>doc</code> will also show the specification details along with the function doc-string.</p>"},{"location":"clojure-spec/functions/documentation/#live-example","title":"Live example","text":"<p>Define the namespace and include clojure spec and clojure.repl (which contains the doc function)</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.repl :as repl]\n            [clojure.spec.alpha :as spec]))\n</code></pre> <p>Print the documentation for the <code>map</code> function</p> <pre><code>(repl/doc map)\n</code></pre> <p>Print the documentation for the <code>:playing-card/suit</code></p> <pre><code>(clojure.repl/doc :playing-card/suit)\n</code></pre> <pre><code> #{:spade :heart :diamond :club}\n</code></pre> <pre><code>(repl/doc :cat-show:cat-bread)\n</code></pre>"},{"location":"clojure-spec/functions/function-definition-specifications/","title":"Function definition specifications","text":"<p><code>clojure.spec.alpha/fdef</code> defines a specification for a function definition, providing specific specification for</p> <ul> <li>arguments passed when calling a function</li> <li>return value expected</li> <li>relationships between arguments and return value</li> </ul>"},{"location":"clojure-spec/functions/function-definition-specifications/#examples","title":"Examples","text":"<p>The <code>practicalli.database-access/new-account-holder</code> function takes a customer details specification and returns an <code>account-holder-id</code> specification.</p> <p>practicalli.database-access/new-account-holder</p> <pre><code>(spec/fdef practicalli.database-access/new-account-holder\n  :args (spec/cat :customer ::customer-details)\n  :ret ::account-holder-id)\n</code></pre>"},{"location":"clojure-spec/functions/higher-order-functions/","title":"Higher order functions","text":"<p>Higher order functions are common in Clojure and spec provides fspec to support spec\u2019ing them.</p> <pre><code>(defn value-added-tax\n  [tax-rate]\n  #(+ (* tax-rate %) %))\n</code></pre> <p>The value-added-tax function returns an anonymous function that adds the value of tax to the given value.</p> <p>Define a namespace for the page and require Clojure Spec</p> <pre><code>(ns practicalli.clojure\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre> <p>Declare a function spec for value-added-tax using <code>clojure.spec.alpha/fspec</code> for the return value:</p> <pre><code>(s/fdef value-added-tax\n  :args (spec/cat :tax-rate number?)\n  :ret (spec/fspec :args (s/cat :value number?)\n                :ret number?))\n</code></pre> <p>The <code>:ret</code> specification uses <code>fspec</code> to declare that the returning function takes and returns a number.</p>"},{"location":"clojure-spec/generative-testing/","title":"Generative testing with Spec and Spec Test","text":"<p>Clojure spec has been used so far to create specifications for both data and functions.</p> <p>Now spec and spec test libraries are used not just validity checking, but also to generate random samples of the data that can be used for extensive testing.</p> <p>Generative testing provides a far more effective alternative to unit testing.</p> <p><code>clojure.spec.test/check/instrument</code> verifies that calls to a function satisfy the function's specification, the <code>:arg</code> in <code>fdef</code>.</p> <p><code>clojure.spec.test/check</code> function generates 1000 data values to be used as the inputs to a function, checks that the invocation of the function satisfies its specification, the <code>:ret</code> and <code>:fn</code> in <code>fdef</code>.  The argument specification, <code>:arg</code> in <code>fdef</code> is used to generate a wide range of results, which are more capable of finding edge cases that fail.</p> <p> </p>"},{"location":"clojure-spec/generative-testing/#example-card-game","title":"Example: card game","text":"<p>practicalli/spec-generative-testing is a simple card game with specifications that are used for basic generative testing.</p> <p> </p>"},{"location":"clojure-spec/generative-testing/#references","title":"References","text":"<ul> <li>Clojure.org guides: Spec - Generators</li> <li>API reference: clojure.spec.gen.alpha</li> <li>API reference: clojure.spec.test.alpha</li> <li>Video: How to do Stateful Property Testing in Clojure?</li> </ul>"},{"location":"clojure-spec/generative-testing/predicate-generators/","title":"Generators for predicate specifications","text":"<p>Specifications are used to generate a wide range of random data.  A generator for the specification is obtained and then data is generated.</p>"},{"location":"clojure-spec/generative-testing/predicate-generators/#predicate-generators","title":"Predicate generators","text":"<pre><code>(spec-gen/generate (spec/gen int?))\n</code></pre> <pre><code>(spec-gen/generate (spec/gen nil?))\n</code></pre> <pre><code>(spec-gen/sample (spec/gen string?))\n</code></pre> <pre><code>(spec-gen/generate (spec/gen #{:club :diamond :heart :spade}))\n</code></pre> <pre><code>(spec-gen/sample (spec/gen #{:club :diamond :heart :spade}))\n</code></pre>"},{"location":"clojure-spec/generative-testing/example-projects/","title":"Example projects using Clojure Spec","text":"Project How the project uses Spec seancorfield/next-jdbc Data specifications using predicates, function definition argument specifications <p>More examples welcome</p> <p>Other example projects that use interesting features of Spec are most welcome.  Raise an issue on the project issue tracker with details.</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/","title":"Projects using Clojure spec - next-jdbc","text":"<p>The next-jdbc project is a modern low-level Clojure wrapper for JDBC-based access to databases.</p> <p>The project defines data specifications using predicates and</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/#defining-specifications","title":"Defining specifications","text":"<p>Specifications are defined within a single file <code>src/next/jdbc/specs.clj</code>.</p> <p>Specifications start with <code>clojure.spec.alpha/def</code> expressions, using predicate functions as specifications.  There is also a custom predicate function called</p> <p>Function definition specifications follow, using the <code>clojure.spec.alpha/fdef</code> function.  The <code>fdef</code> functions define the specification for the arguments of each function.  The <code>fdef</code> function name is the same as the function definition it is defining a specification for.</p>"},{"location":"clojure-spec/generative-testing/example-projects/next-jdbc/#instrumenting-specifications","title":"Instrumenting specifications","text":"<p>Instrumenting functions provides automatic checking that argument in a function call conforms to the specification.</p> <p>Rather than write individual expressions to instrument each function, a var called <code>fns-with-specs</code> contains a collection of names for all the <code>fdef</code> function definition specifications.</p> <pre><code>(def ^:private fns-with-specs\n  [`jdbc/get-datasource\n   `jdbc/get-connection\n   `jdbc/prepare\n   `jdbc/plan\n   `jdbc/execute!\n   `jdbc/execute-one!\n   `jdbc/transact\n   `jdbc/with-transaction\n   `connection/-&gt;pool\n   `prepare/execute-batch!\n   `prepare/set-parameters\n   `prepare/statement\n   `sql/insert!\n   `sql/insert-multi!\n   `sql/query\n   `sql/find-by-keys\n   `sql/get-by-id\n   `sql/update!\n   `sql/delete!])\n</code></pre> <p>Instrument all the functions by passing <code>fns-with-specs</code> as an argument to the <code>clojure.spec.test.alpha/instrument</code> function.</p> <p>This call is wrapped in a simple handler function for convenience.</p> <pre><code>(defn instrument []\n  (clojure.spec.test.alpha/instrument fns-with-specs))\n</code></pre> <p>To remove the checking of argument specifications, <code>clojure.spec.test.alpha/unstrument</code> is passed <code>fns-with-specs</code>, again wrapped in a convinced function.</p> <pre><code>(defn unstrument []\n  (clojure.spec.test.alpha/unstrument fns-with-specs))\n</code></pre>"},{"location":"clojure-spec/projects/","title":"Clojure Spec Projects","text":"<p>A series of projects showing approaches to using specifications and generating data for testing.</p> Project Description card game writing specifications and generating data from those specifications banking-on-clojure simplified online bank account using TDD, data and functional specifications and generative testing Bonbon card game A flavorful card game with clojure spec Genetic Programming With clojure.spec https://www.youtube.com/watch?v=xvk-Gnydn54 ClojureScript game with spec"},{"location":"clojure-spec/projects/#references","title":"References","text":"<ul> <li>Practicalli - Clojure Spec playlist - live coding to define specifications and generative testing</li> </ul>"},{"location":"clojure-spec/projects/bank-account/","title":"Spec project: Bank Account","text":"<p>A relatively simple bank account application with data and function specifications, including generative testing data and function instrumentation.</p>"},{"location":"clojure-spec/projects/bank-account/#hintunder-active-development","title":"Hint::Under active development","text":"<p>Developed as part of the Practicalli study guide live broadcasts</p>"},{"location":"clojure-spec/projects/bank-account/#create-depsedn-project","title":"Create deps.edn project","text":"<p>Use Clojure CLI and <code>clj-new</code></p> <pre><code>clojure -M:new app practicalli/banking-on-clojure\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/#hintpracticallibanking-on-clojure-repository","title":"Hint::practicalli/banking-on-clojure repository","text":"<p>practicalli/banking-on-clojure repository contains the latest code to date for this project.</p>"},{"location":"clojure-spec/projects/bank-account/#outline-design-of-project","title":"Outline design of project","text":"<p>Data Specifications are created for</p> <ul> <li>Customer Details \u2714</li> <li>Account holder \u2714</li> <li>Bank account</li> <li>Multiple Bank accounts</li> <li>Credit Card</li> <li>Mortgage</li> </ul> <p>Functions and specifications are created for</p> <ul> <li>register-account-holder \u2714</li> <li>open-credit-account</li> <li>open-savings-account</li> <li>open-credit-card-account</li> <li>open-mortgage-account</li> <li>Make a payment</li> <li>Send account notification</li> <li>Check for overdraft</li> </ul>"},{"location":"clojure-spec/projects/bank-account/#development-workflow","title":"Development Workflow","text":"<ul> <li>Write a failing test \u2714</li> <li>write mock data \u2714</li> <li>write an function definition that returns the argument \u2714</li> <li>run tests - tests should fail \u2714</li> <li>write a spec for the functions argument - customer \u2714</li> <li>write a spec for the return value \u2714</li> <li>write a spec for relationship between args and return value</li> <li>replace the mock data with generated values from specification \u2714</li> <li>update functions and make tests pass \u2714</li> <li>instrument functions</li> <li>run specification checks</li> </ul> <p>\u2714</p> <p>Images to add</p> <p>Running tests that fail on a spec in CIDER spacemacs-cider-test-spec-fail-banking-on-clojure-project.png</p> <p>Running tests that fail on a spec on CircleCI circle-ci-banking-on-clojure-spec-test-runner-fail-register-account-holder-did-not-conform-to-spec.png</p>"},{"location":"clojure-spec/projects/bank-account/account-holder-specification/","title":"Account holder specification","text":"<p>The account holder has the same information as custom details with the addition of an account-id</p> <p>In the register-account-holder a uuid is generated for the account id, So a spec can be defined for this type</p> <pre><code>(spec/def ::account-id uuid?)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/account-holder-specification/#design-decision-hierarchical-or-composite","title":"Design decision: hierarchical or composite","text":"<p>There are several approaches to combining, depending on the shape of the data used</p> <p>The account holder is a hash-map, so <code>spec/keys</code> will create the map from specification keys</p> <p>Including the customer-details specification in <code>spec/keys</code> would include the customer details as a nested hash-map</p> <pre><code>(spec/def ::account-holder-hierarchy\n  (spec/keys\n    :req [::account-id ::customer-details]))\n</code></pre> <p>A valid data structure for this specification is a map with two keys, <code>account-id</code> and <code>customer-details</code>. <code>account-id</code> is a uuid value, customer-details is a hash-map of values that conform to the customer-details specification</p> <pre><code>(spec/valid? ::account-holder-hierarchy\n             #::{:account-id       (java.util.UUID/randomUUID)\n                 :customer-details #:: {:first-name          \"Jenny\"\n                                        :last-name           \"Jetpack\"\n                                        :email-address       \"jenny@jetpack.org\"\n                                        :residential-address \"42 meaning of life street, Earth\"\n                                        :postal-code         \"AB3 0EF\"\n                                        :social-security-id  \"123456789\"}})\n;; =&gt; true\n</code></pre> <p>Flat data structures are usually preferred in Clojure over a nested hierarchy. Rather than use the ::customer-details specification as a key in the <code>spec/keys</code> expression. The individual specifications that make up ::customer-details can be used.</p> <pre><code>(spec/def ::account-holder-composition\n  (spec/keys\n    :req [::account-id ::first-name ::last-name ::email-address ::residential-address ::social-security-id]))\n</code></pre> <pre><code>(spec/valid? ::account-holder-composition\n             #::{:account-id          (java.util.UUID/randomUUID)\n                 :first-name          \"Jenny\"\n                 :last-name           \"Jetpack\"\n                 :email-address       \"jenny@jetpack.org\"\n                 :residential-address \"42 meaning of life street, Earth\"\n                 :postal-code         \"AB3 0EF\"\n                 :social-security-id  \"123456789\"})\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/","title":"Customer details specification","text":"<p>Create a new file for the specifications, <code>src/practicalli/banking_specifications.cljc</code>, with the namespace <code>practicalli.banking-specifications</code>.</p> <p>Require the <code>clojure.spec.alpha</code> library with an alias of <code>spec</code>.</p> <pre><code>(ns practicalli.banking-specifications\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#define-basic-customer-details","title":"Define basic customer details","text":"<p>Define a specification for the customer-details map, composed of all the required keys that define a customer.</p> <p>The bank legally requires specific information about a customer in order to add them as an account holder</p> <pre><code>(spec/def ::first-name string?)\n(spec/def ::last-name string?)\n(spec/def ::email-address string?)\n</code></pre> <pre><code>(spec/def ::email-address\n  (spec/and string?\n            #(re-matches #\"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,63}$\"\n                         %)))\n</code></pre> <p>This specification will require a custom generator</p> <p>A residential address is made from several pieces of information and is defined as a composite specification, from several specifications.</p> <pre><code>(spec/def ::house-name-number (spec/or :string string?\n                                       :number int?))\n(spec/def ::street-name string?)\n(spec/def ::post-code string?)\n(spec/def ::county string?)\n(spec/def ::country string?)\n</code></pre> <pre><code>(spec/def ::residential-address (spec/keys :req [::house-name-number ::street-name ::post-code]\n                                           :opt [::county ::country]))\n</code></pre> <p>A social security number specification is also a candidate for a composite specification. Social security numbers may take different forms and even have different names in different countries, eg. the USA SSN is a nine-digit number in the format \"AAA-GG-SSSS\"</p> <p>In the UK the social security number is called the National Insurance number and is of the form QQ123456C</p> <pre><code>(spec/def ::social-security-id-uk string?)\n(spec/def ::social-security-id-usa string?)\n</code></pre> <pre><code>(defn social-security-number-usa? [value] (= 9 (count value)))\n(defn social-security-number-uk? [value] (= 11 (count value)))\n(spec/def ::social-security-id-usa (spec/and string? social-security-number-usa?))\n(spec/def ::social-security-id-uk (spec/and string? social-security-number-uk?))\n</code></pre> <p>These specifications required a custom generator in order to produce correct data each time.</p> <p>A general social security specification can now be defined, with one of any of the country specific specifications</p> <pre><code>(spec/def ::social-security-id (spec/or ::social-security-id-uk\n                                        ::social-security-id-usa))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#infoa-more-detailed-email-specification","title":"INFO::A more detailed email specification","text":"<p>Use a regular expression to define the syntax of an email address, eg. jenny@jetpack.org</p>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#infodetailed-social-security-numbers-would-check-the-different-forms","title":"INFO::Detailed social security numbers would check the different forms","text":"<p>Predicate functions can be defined to check for the size of the different social security forms.</p>"},{"location":"clojure-spec/projects/bank-account/customer-details-specification/#composing-the-customer-details-specification","title":"Composing the customer details specification","text":"<p>A customer details specification is a hash-map of key value pairs. The keys are the specifications that have just been defined.</p> <p><code>spec/keys</code> creates a specification for a hash-map with required and optional keys.  <code>spec/keys</code> also includes a check for a map, so no explicit check for a map is required.</p> <pre><code>(spec/def ::customer-details\n  (spec/keys\n    :req [::first-name ::last-name ::email-address ::residential-address ::social-security-id]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/","title":"Specifications for function definitions - <code>fdef</code>","text":"<p>Create a <code>spec/fdef</code> for the register-account-holder function</p> <p><code>clojure.spec.alpha/fdef</code> defines a specification for a function definition, <code>defn</code>. Specifications can attached to the arguments using <code>:args</code>, the return value using <code>:ret</code> and the relationship between the two using <code>fn</code>.</p> <p><code>:args</code>, <code>:ret</code> and <code>fn</code> are optional, although <code>args</code> and <code>ret</code> are required if you want to use <code>:fn</code></p>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#add-a-spec-to-cover-the-function-arguments","title":"Add a spec to cover the function arguments","text":"<p><code>:args</code> is a compound specification that covers all the function arguments. The <code>:args</code> spec is invoked with the arguments in a list, so working with them is like using apply.</p> <p>Using regular expressions we can find the right arguments to give to the specification. Regular expression spec functions include</p> <ul> <li><code>spec/cat</code></li> <li><code>spec/alt</code></li> <li><code>spec/*</code></li> </ul> <p>The register-account-holder only takes one argument, so <code>spec/cat</code> is used to bind a local key to the specification.</p> <p>The function is defined in the <code>practicalli.banking-on-clojure</code> namespace.  Require that namespace in the current <code>ns</code> form.</p> <pre><code>(ns practicalli.banking-specifications\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]\n\n            [practicalli.banking-on-clojure :as SUT]))\n</code></pre> <p>The <code>SUT</code> alias is used for the banking-on-clojure namespace, as is done with <code>clojure.test</code> unit test namespaces.</p> <pre><code>(spec/fdef SUT/register-account-holder\n  :args (spec/cat :customer\n                  :practicalli.bank-account-spec/customer-details))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#checking-function-calls-against-the-spec-instrument","title":"Checking function calls against the spec - instrument","text":"<p><code>spec/fdef</code> by itself does not run checks against the specs</p> <pre><code>(register-account-holder {})\n;; =&gt; {:account-id #uuid \"3a6dddb7-dd87-485e-90f8-8c8975302845\"}\n</code></pre> <p>Require the Clojure spec test library</p> <pre><code>(require '[clojure.spec.test.alpha :as spec-test])\n</code></pre> <p><code>spec/instrument</code> will add a run time check for the specification</p> <pre><code>(spec-test/instrument `SUT/register-account-holder)\n</code></pre> <p>No the function is instrumented, data used as arguments of a function call will be checked against the specification.</p> <pre><code>(register-account-holder {::bad \"data\"})\n</code></pre> <p>This function call throws an exception because of the specification attached to the <code>:args</code> section of the <code>fdef</code> specification.</p> <p>The error report provides detailed and quite clear information to help diagnose the issue</p> <pre><code> 1. Unhandled clojure.lang.ExceptionInfo\n Spec assertion failed.\n\n Spec: #object[clojure.spec.alpha$regex_spec_impl$reify__2509 0x12b66a86 \"clojure.spec.alpha$regex_spec_impl$reify__2509@12b66a86\"]\n Value: (#:practicalli.bank-account-design-journal{:bad \"data\"})\n\n Problems:\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/first-name)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/last-name)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/email-address)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/residential-address)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n\n val: #:practicalli.bank-account-design-journal{:bad \"data\"}\n in: [0]\n failed: (contains? % :practicalli.bank-account-spec/social-security-id)\n spec: :practicalli.bank-account-spec/customer-details\n at: [:customer]\n</code></pre> <p>Calling the register-account-holder with a value that conforms to the bank-account-spec for customer details returns the new value for account-holder</p> <pre><code>(register-account-holder\n  #:practicalli.bank-account-spec\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n\n;; =&gt; {:practicalli.bank-account-spec/first-name \"Jenny\", :practicalli.bank-account-spec/last-name \"Jetpack\", :practicalli.bank-account-spec/email-address \"jenny@jetpack.org\", :practicalli.bank-account-spec/residential-address \"42 meaning of life street, Earth\", :practicalli.bank-account-spec/postal-code \"AB3 0EF\", :practicalli.bank-account-spec/social-security-id \"123456789\", :account-id #uuid \"e0f327de-4e92-479e-a9de-468e2c7c0e6d\"}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#add-a-specification-to-the-return-value","title":"Add a specification to the return value","text":"<p>Attach the account-holder details specification to <code>:ret</code></p> <pre><code>(spec/fdef register-account-holder\n  :args (spec/cat :customer\n                  :practicalli.bank-account-spec/customer-details)\n  :ret :practicalli.bank-account-spec/account-holder)\n</code></pre> <p>If the <code>register-account-holder</code> logic changes to return a different value that the return spec, then an exception is raised</p> <p>Returns an integer rather than a uuid</p> <pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n  [customer-details]\n\n  (assoc customer-details\n         :practicalli.bank-account-spec/account-id\n         (rand-int 100000)\n         #_(java.util.UUID/randomUUID)))\n</code></pre> <p>So this should fail</p> <pre><code>(register-account-holder\n  #:practicalli.bank-account-spec\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <p>It still works as <code>spec-test/instrument</code> only checks the args value.</p> <p><code>spec-test/check</code> will test the return value with generated tests</p> <pre><code>(require '[clojure.spec.gen.alpha :as spec-gen])\n</code></pre> <pre><code>(spec-test/check `SUT/register-account-holder)\n</code></pre> <p>The result is 100 generated tests that all fail, because the function was changed to return integers, not uuids</p> <pre><code> 1. Caused by clojure.lang.ExceptionInfo\n Couldn't satisfy such-that predicate after 100 tries.\n {:pred      #function[clojure.spec.alpha/gensub/fn--1876],\n  :gen       {:gen #function[clojure.test.check.generators/such-that/fn--8322]},\n  :max-tries 100}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#change-the-function-back-again","title":"Change the function back again","text":"<pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n  [customer-details]\n\n  (assoc customer-details\n         :practicalli.bank-account-spec/account-id\n         (java.util.UUID/randomUUID)))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/function-specifications/#instrument-the-function","title":"Instrument the function","text":"<p>Testing function calls against the specification</p> <p>Requires the spec test namespace</p> <pre><code>(require '[clojure.spec.test.alpha :as spec-test])\n</code></pre> <p>Instrument the spec to add checking, this only checks the arguments are correct.</p> <pre><code>(spec-test/instrument `practicalli.bank-account/register-account-holder)\n</code></pre> <pre><code>(register-account-holder {:first-name          \"Jenny\"\n                          :last-name           \"Jetpack\"\n                          :email-address       \"jenny@jetpack.org\"\n                          :residential-address \"42 meaning of life street\"\n                          :postal-code         \"AB3 0EF\"\n                          :social-security-id  \"123456789\"})\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/","title":"Generate test data","text":""},{"location":"clojure-spec/projects/bank-account/generate-test-data/#generate-test-data-from-specifications","title":"Generate test data from Specifications","text":"<p>Now there are specifications for the customer-details and account-details, spec can generate random data for use with tests.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#add-requires-to-the-test-namespace","title":"Add requires to the test namespace","text":"<p>Edit the <code>src/test/practicalli/banking_on_clojure.clj</code> and add requires for the <code>banking-specifications</code>, <code>clojure.spec.alpha</code> and <code>clojure.spec.test.alpha</code>.</p> <pre><code>(ns practicalli.banking-on-clojure-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [clojure.spec.alpha :as spec]\n            [clojure.spec.test.alpha :as spec-test]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [practicalli.banking-on-clojure :as SUT]\n            [practicalli.banking-specifications]))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#using-generators-to-generate-data","title":"Using Generators to generate data","text":"<p>Test data can now be generated from this specification, creating values for each key in the hash-map.</p> <p>The ::email-address specification has been simplified, as the regular expression version requires a custom generator (no built in generator to support this specification).  The simplified email specification is:</p> <pre><code>(spec/def ::email-address string?)\n</code></pre> <p>With the simplified email specification, the customer-details specification can be used to generate all the data using the built in clojure.spec.alpha generators.</p> <pre><code>(spec-gen/generate (spec/gen :practicalli.banking-specifications/customer-details))\n\n;; =&gt; #:practicalli.banking-specifications\n{:first-name \"r7q9RFB202v7a69z\",\n :last-name \"6N5\",\n :email-address \"L6dd946p680P0pIYZ33CGZd0\",\n :residential-address\n   #:practicalli.banking-specifications{\n      :house-name-number \"gCuRMe0C8\",\n      :street-name \"5\",\n      :post-code \"VN\"},\n      :social-security-id \"a7P0xfBNPv6\"}\n</code></pre> <p>Bind the result of this function to a name and it can be used as mock data throughout the unit tests defined.</p> <pre><code>(defn customer-details-mock-data\n  (spec-gen/generate (spec/gen :practicalli.banking-specifications/customer-details)))\n</code></pre> <p>The generated data can also be used with function definitions and <code>clojure.spec.test.alpha/check</code> function.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#hintlibraries-for-custom-generators","title":"Hint::Libraries for custom generators","text":"<p>gfredericks/test.chuck is a utility library for test.check and will work with clojure spec as its a wrapper around test.check.</p> <p>lambdaisland/regal also has test.check generators that can be used for regular expressions defined with the regal (hiccup style) syntax.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#generating-more-than-one-value-for-a-specification","title":"Generating more than one value for a specification","text":"<p><code>clojure.spec.gen.alpha/sample</code> will generate 10 random values from the specification</p> <pre><code>(spec-gen/sample (spec/gen :practicalli.banking-specifications/customer-details))\n\n;; =&gt; (#:practicalli.banking-specifications{:first-name \"\", :last-name \"\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:country \"\", :county \"\", :house-name-number \"\", :street-name \"\", :post-code \"\"}, :social-security-id \"2P902qTJCP6\"}\n\n#:practicalli.banking-specifications{:first-name \"\", :last-name \"z\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:house-name-number 0, :street-name \"\", :post-code \"R\"}, :social-security-id \"3dDBA7pa98r\"}\n\n#:practicalli.banking-specifications{:first-name \"nQ\", :last-name \"w\", :email-address \"h6\", :residential-address #:practicalli.banking-specifications{:country \"\", :county \"7u\", :house-name-number \"\", :street-name \"87\", :post-code \"\"}, :social-security-id \"x57pf2H2i16\"}\n\n#:practicalli.banking-specifications{:first-name \"ac\", :last-name \"L0x\", :email-address \"S\", :residential-address #:practicalli.banking-specifications{:country \"Xd\", :county \"\", :house-name-number \"P\", :street-name \"\", :post-code \"\"}, :social-security-id \"j5iTA70j9FW\"}\n\n#:practicalli.banking-specifications{:first-name \"e\", :last-name \"ic\", :email-address \"15G\", :residential-address #:practicalli.banking-specifications{:house-name-number \"\", :street-name \"Nj\", :post-code \"f\"}, :social-security-id \"I83rx1wUj07\"}\n\n#:practicalli.banking-specifications{:first-name \"zPr\", :last-name \"r\", :email-address \"hsVz\", :residential-address #:practicalli.banking-specifications{:country \"W\", :house-name-number \"S\", :street-name \"64\", :post-code \"85s25\"}, :social-security-id \"8EEDiy28SX7\"}\n\n#:practicalli.banking-specifications{:first-name \"QzoV\", :last-name \"\", :email-address \"iS\", :residential-address #:practicalli.banking-specifications{:county \"OaMj9\", :house-name-number 1, :street-name \"pzc0ji\", :post-code \"tv1\"}, :social-security-id \"9z88KM5TLKK\"}\n\n#:practicalli.banking-specifications{:first-name \"w73AA\", :last-name \"\", :email-address \"\", :residential-address #:practicalli.banking-specifications{:county \"sUj\", :house-name-number 4, :street-name \"jw\", :post-code \"652Z\"}, :social-security-id \"rZMUTPK72N6\"}\n\n#:practicalli.banking-specifications{:first-name \"j09f\", :last-name \"EoU\", :email-address \"sA82q\", :residential-address #:practicalli.banking-specifications{:country \"28nyq3\", :county \"5PURE\", :house-name-number \"1NzKwe\", :street-name \"28Y\", :post-code \"t\"}, :social-security-id \"yNBdc7M29Io\"}\n\n#:practicalli.banking-specifications{:first-name \"Xa38iX8FP\", :last-name \"u4G\", :email-address \"Ne1w25nJ\", :residential-address #:practicalli.banking-specifications{:country \"H07\", :house-name-number -17, :street-name \"jWRhfrrz9\", :post-code \"sF9\"}, :social-security-id \"IX2w8Xx8u0n\"})\n</code></pre> <p>Generating multiple result is useful if a collection of customer details is required for testing purposes.</p>"},{"location":"clojure-spec/projects/bank-account/generate-test-data/#exercising-a-specification","title":"Exercising a specification","text":"<p><code>clojure.spec.test.alpha/exercise</code> returns pairs of generated and conformed values for a spec. exercise by default produces 10 samples (like sample) but you can pass both functions a number indicating the number of samples to produce.</p> <pre><code>(spec/exercise (spec/cat :practicalli.banking-specifications/first-name :practicalli.banking-specifications/last-name))\n\n;; =&gt; ([(\"\") #:practicalli.banking-specifications{:first-name \"\"}]\n       [(\"6\") #:practicalli.banking-specifications{:first-name \"6\"}]\n       [(\"\") #:practicalli.banking-specifications{:first-name \"\"}]\n       [(\"6\") #:practicalli.banking-specifications{:first-name \"6\"}]\n       [(\"W\") #:practicalli.banking-specifications{:first-name \"W\"}]\n       [(\"ljooD\") #:practicalli.banking-specifications{:first-name \"ljooD\"}]\n       [(\"704d5x\") #:practicalli.banking-specifications{:first-name \"704d5x\"}]\n       [(\"EZyBT\") #:practicalli.banking-specifications{:first-name \"EZyBT\"}]\n       [(\"1e6\") #:practicalli.banking-specifications{:first-name \"1e6\"}]\n       [(\"v\") #:practicalli.banking-specifications{:first-name \"v\"}])\n</code></pre> <p><code>clojure.spec.test.alpha/exercise-fn</code> provides the same service but for function specifications (<code>fdef</code>).</p>"},{"location":"clojure-spec/projects/bank-account/rebel-readline/","title":"Using the project in rebel readline","text":"<p>Start the rebel REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Once rebel has started a prompt will be displayed.</p> <p>First required the main namespace, containing the functions of the application.  This loads the code in that namespace into the REPL.</p> <pre><code>(require 'practicalli.banking-on-clojure)\n</code></pre> <p>Now add the specifications for the project</p> <pre><code>(require 'practicalli.banking-on-clojure)\n</code></pre> <p>? When does the TAB completion start to work ?</p> <p>Testing the specifications</p> <p>First change into the specifications namespace so the fully qualified names of the specs are not required.</p> <pre><code>(in-ns 'practicalli.banking-specifications)\n</code></pre> <p>Generate sample data from the specifications</p> <pre><code>(spec-gen/sample (spec/gen ::account-id))\n</code></pre> <p>The function specifications and the instrument functions are loaded from the requires, so test by calling the instrumented functions, first with bad data and then with correct data.</p> <pre><code>(register-account-holder {})\n</code></pre> <p>Use the specifications to generate good data</p> <pre><code>(register-account-holder ::customer-details)\n</code></pre> <p>Run generative tests on functions to check the return and fn values</p> <pre><code>(spec-test/check `register-account-holder)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/rebel-readline/#hinttodo-add-screenshots-using-rebel-readline-repl","title":"Hint::TODO: add screenshots using Rebel readline REPL","text":""},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/","title":"Test functions against spec","text":""},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#generative-testing-with-check","title":"Generative testing with <code>check</code>","text":"<p><code>clojure.spec.test.alpha/check</code> generates 1000 values from the argument section of a function definition specification.</p> <p>Pass the name of the function definition that has a specification to the <code>check</code> function.</p> <pre><code>(spec-test/check ``register-account-holder`)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#limiting-the-generated-data","title":"Limiting the generated data","text":"<p>1000 tests can take a noticeable time to run, so check is not as often used during active development, as it would slow down the normal fast feedback cycle with Clojure.</p> <p><code>check</code> takes an optional second argument which configures how the function operates.  Passing a hash-map as a second argument will set the number of data values generated <code>{:clojure.spec.test.check/opts {:num-tests 100}}</code></p> <pre><code>(spec-test/check\n  `register-account-holder\n  {:clojure.spec.test.check/opts {:num-tests 100}})\n</code></pre> <p>Configuring <code>check</code> to run fewer tests provides a simple way to test multiple values without slowing down the development workflow.</p>"},{"location":"clojure-spec/projects/bank-account/test-functions-against-spec/#reporting-on-generative-testing","title":"Reporting on Generative testing","text":"<p><code>clojure.spec.test.alpha/summarize-results</code> will return a brief summary including the total number of results and a count for how many results passed and failed.</p> <pre><code>(spec-test/summarize-results\n  (spec-test/check `register-customer\n                   {:clojure.spec.test.check/opts {:num-tests 10}}))\n</code></pre> <p>Use the threading macro to summarize the results of multiple check operations</p> <pre><code>(-&gt;&gt; (spec-test/check `register-account-holder)\n     (spec-test/check `open-current-bank-account)\n     (spec-test/summarize-results))\n</code></pre> <p>If this expression is bound to a name then it can be called when ever the full suite of <code>check</code> generative testing is required.</p>"},{"location":"clojure-spec/projects/bank-account/unit-tests-with-spec/","title":"Unit tests with specs","text":"<p>Now that customer data and account-holder data has a specification, we can use the <code>clojure.spec.alpha/valid?</code> in the unity test code, as that function returns true or false.</p> <p>In this example the result of a call to <code>register-account-holder</code> is checked to see if it is valid against the <code>::account-holder</code> specification.  This simplifies the code needed in unit test assertions, as Clojure spec is doing the work.</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (SUT/register-account-holder customer-mock)))\n           (set (keys account-holder))))\n\n    (is (spec/valid? :practicalli.bank-account-spec/account-holder\n                     (SUT/register-account-holder customer-mock) ) )\n    ))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/","title":"Testing data Specifications","text":"<p>The specifications defined so far can be tested with specific data, using the <code>conform</code> or <code>valid?</code> functions.</p> <p>Generating sample data from the specifications also provides useful feedback on how well the specifications are defined.</p>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#generating-data-from-specifications","title":"Generating data from specifications","text":"<p>Test data specifications by generating sample data from those specifications.</p> <p>Evaluating these functions several times is a quick way to identifies specifications that may require custom generators. If individual specifications do not generate consistent data, then incorrect results may occur during composite data specifications or function specifications.</p> <pre><code>(spec-gen/sample (spec/gen ::first-name))\n(spec-gen/sample (spec/gen ::last-name))\n(spec-gen/sample (spec/gen ::email-address))\n(spec-gen/sample (spec/gen ::house-name-number))\n(spec-gen/sample (spec/gen ::street-name))\n(spec-gen/sample (spec/gen ::post-code))\n(spec-gen/sample (spec/gen ::county))\n(spec-gen/sample (spec/gen ::country))\n(spec-gen/sample (spec/gen ::residential-address))\n(spec-gen/sample (spec/gen ::social-security-id-uk))\n(spec-gen/sample (spec/gen ::social-security-id-usa))\n(spec-gen/sample (spec/gen ::social-security-id))\n(spec-gen/sample (spec/gen ::customer-details))\n(spec-gen/sample (spec/gen ::account-holder))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#validating-the-customer-details-specifications","title":"Validating the customer details specifications","text":"<p>The specifications can be checked using the conform or valid? functions with example data.</p> <p>Check an example hash-map from our test conforms to the specification</p> <pre><code>(spec/conform ::customer-details\n              {:first-name          \"Jenny\"\n               :last-name           \"Jetpack\"\n               :email-address       \"jenny@jetpack.org\"\n               :residential-address \"42 meaning of life street\"\n               :postal-code         \"AB3 0EF\"\n               :social-security-id  \"123456789\"})\n;; =&gt; :clojure.spec.alpha/invalid\n</code></pre> <p>The mock test data does not confirm to the specification, even though it has all the same keys as the map in the specification</p> <pre><code>(spec/valid? ::customer-details\n             {:first-name          \"Jenny\"\n              :last-name           \"Jetpack\"\n              :email-address       \"jenny@jetpack.org\"\n              :residential-address \"42 meaning of life street\"\n              :postal-code         \"AB3 0EF\"\n              :social-security-id  \"123456789\"})\n;; =&gt; false\n</code></pre> <p><code>spec/explain</code> will provide more information to help diagnose the issue</p> <pre><code>(spec/explain ::customer-details\n              {:first-name          \"Jenny\"\n               :last-name           \"Jetpack\"\n               :email-address       \"jenny@jetpack.org\"\n               :residential-address \"42 meaning of life street\"\n               :postal-code         \"AB3 0EF\"\n               :social-security-id  \"123456789\"})\n\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/first-name) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/last-name) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/email-address) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/residential-address) spec: :practicalli.bank-account-design-journal/customer-details\n;; {:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n;; - failed: (contains? % :practicalli.bank-account-design-journal/social-security-id) spec: :practicalli.bank-account-design-journal/customer-details\n</code></pre> <p>The <code>::customer-details</code> spec is given a map with unqualified keys and is failing the <code>:req</code> part of the <code>spec/keys</code> part of the specification</p>"},{"location":"clojure-spec/projects/bank-account/validate-customer-details-specification/#qualifying-keys-with-auto-resolve-macro","title":"Qualifying keys with auto-resolve macro","text":"<p>The auto-resolve macro, <code>#::</code> will add the current namespace to all the keys in a hash-map</p> <p>Change the test data to use qualified keys by adding the</p> <pre><code>(spec/conform ::customer-details\n              #::{:first-name          \"Jenny\"\n                  :last-name           \"Jetpack\"\n                  :email-address       \"jenny@jetpack.org\"\n                  :residential-address \"42 meaning of life street\"\n                  :postal-code         \"AB3 0EF\"\n                  :social-security-id  \"123456789\"}  )\n;; =&gt; #:practicalli.bank-account-design-journal{:first-name \"Jenny\", :last-name \"Jetpack\", :email-address \"jenny@jetpack.org\", :residential-address \"42 meaning of life street\", :postal-code \"AB3 0EF\", :social-security-id \"123456789\"}\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/","title":"Write failing tests","text":"<p>In Test Driven Development style, first write unit tests for the banking functions.</p> <p>Edit the <code>src/practicalli/banking_on_clojure_test.clj</code> and add <code>deftest</code> tests</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (register-account-holder {})))\n           (set (keys {:account-id \"123\" :customer-name \"Jenny Jetpack\"}))))))\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/#write-a-function-stub-to-run-the-tests","title":"Write a function stub to run the tests","text":"<p>The tests cannot run unless they call the function to be tested.  A common approach it to write a function that returns the argument.</p> <pre><code>(defn register-account-holder\n  \"Register a new customer with the bank\n  Arguments:\n  - hash-map of customer-details\n  Return:\n  - hash-map of an account-holder (adds account id)\"\n\n  [customer-details]\n\n  customer-details)\n</code></pre>"},{"location":"clojure-spec/projects/bank-account/write-failing-tests/#add-mock-data","title":"Add mock data","text":"<p>Define some initial mock data to use with the unit tests</p> <pre><code>(def customer-mock\n  {:first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <pre><code>account is a customer with a bank account id added\n\n(def account-holder-mock\n  {:account-id           #uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\"\n   :first-name          \"Jenny\"\n   :last-name           \"Jetpack\"\n   :email-address       \"jenny@jetpack.org\"\n   :residential-address \"42 meaning of life street, Earth\"\n   :postal-code         \"AB3 0EF\"\n   :social-security-id  \"123456789\"})\n</code></pre> <p>Update the test to use the mock data.</p> <pre><code>(deftest register-account-holder-test\n  (testing \"Basic registration - happy path\"\n    (is (= (set (keys (register-account-holder customer-mock)))\n           (set (keys account-holder-mock))))))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/","title":"Card game: spec and generative testing","text":"<p>Define a data specification that represent a deck of playing cards, adding functional specifictations to check the values passed to the functions use to play a card game.</p> <p>spec generators are used to return varied sample data from those specifications. Function definitions are instrumented and check for correct arguments when those functions are called.</p>"},{"location":"clojure-spec/projects/card-game/#create-a-new-project","title":"Create a new project","text":"<p>Create a new Clojure project using <code>:project/create</code> from  Practicalli Clojure CLI Config or add an alias definition of your choosing to the Clojure CLI user configuration.</p> <pre><code>clojure -T:project/create :template app :name practicalli/card-game\n</code></pre> <p>Open the <code>src/practicalli/card_game.clj</code> file and require the <code>clojure.spec.alpha</code> namespace</p> <pre><code>(ns practicalli.card-game.clj\n  (:require [clojure.spec.alpha :as spec]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#playing-card-specifications","title":"Playing card specifications","text":"<p>A playing card has a face value and a suit. There are 4 suits in a card deck.</p> <p>A specification for the possible suits can be defined using literal values</p> <pre><code>(spec/def ::suits #{:clubs :diamonds :hearts :spades})\n</code></pre> <p>Define a predicate function to check a value conforms to the spec using the pattern matching that is build-in to the Clojure <code>set</code> data type.</p> <pre><code>(def suits? #{:clubs :diamonds :hearts :spades})\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#card-game-decks","title":"Card game decks","text":"<p>Suits from different regions are called by different names.  Each of these suits can be their own spec.</p> <pre><code>(spec/def ::suits-french #{:hearts :tiles :clovers :pikes})\n(spec/def ::suits-german #{:hearts :bells :acorns :leaves})\n(spec/def ::suits-spanish #{:cups :coins :clubs :swords})\n(spec/def ::suits-italian #{:cups :coins :clubs :swords})\n(spec/def ::suits-swiss-german #{:roses :bells :acorns :shields})\n</code></pre> <p>A composite specification called <code>::card-suits</code> provides a simple abstraction over all the variations of suits.  Using <code>::card-suits</code> will be satisfied with any region specific suits.</p> <pre><code>(spec/def ::card-suits\n  (spec/or :french ::suits-french\n           :german ::suits-german\n           :spanish ::suits-spanish\n           :italian ::suits-italian\n           :swiss-german ::suits-swiss-german\n           :international ::suits-international))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#define-an-alias","title":"Define an alias","text":"<p>Jack queen king are called face cards in the USA and occasionally referred to as court cards in the UK.</p> <p>Define a spec for <code>::face-cards</code> and then define <code>:court-cards</code> and alias</p> <pre><code>(spec/def ::face-cards #{:jack :queen :king :ace})\n(spec/def ::court-cards ::face-cards)\n</code></pre> <p>Any value that conforms to the <code>::face-card</code> specification also conforms to the <code>::court-cards</code> specification.</p> <pre><code>(spec/conform ::court-cards :ace)\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#playing-card-rank","title":"Playing card rank","text":"<p>Each suit in the deck has the same rank of cards explicitly defining a rank</p> <pre><code>(spec/def ::rank #{:ace 2 3 4 5 6 7 8 9 10 :jack :queen :king})\n</code></pre> <p>Rank can be defined more succinctly with the <code>clojure.core/range</code> function.  The expression <code>(range 2 11)</code> will generates a sequence of integer numbers from 2 to 10 (the end number is exclusive, so 11 is not in the sequence).</p> <p>Using <code>clojure.core/into</code> this range of numbers can be added to the face card values.</p> <pre><code>(into #{:ace :jack :queen :king} (range 2 11))\n</code></pre> <p>The <code>::rank</code> specification now generates all the possible values for playing cards.</p> <pre><code>(spec/def ::rank (into #{:ace :jack :queen :king} (range 2 11)))\n</code></pre> <p>The specification only checks to see if a value is in the set, the order of the values in the set is irrelevant.</p>"},{"location":"clojure-spec/projects/card-game/#playing-card","title":"Playing Card","text":"<p>A playing card is a combination of suit and face value, a pair of values, referred to as a tuple.</p> <p>Clojure spec has a <code>tuple</code> function, however, we need to define some predicates first</p> <pre><code>(spec/def ::playing-card (spec/tuple ::rank ::suits ))\n</code></pre> <p>Use the spec with values to see if they conform.  Try you own values for a playing card.</p> <pre><code>(spec/conform ::playing-card [:ace :spades])\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#game-specs","title":"Game specs","text":"<p>Define specifications for data used to represent players and the overall card game.</p> <p>The player name is a very simple spec.</p> <pre><code>(spec/def ::name string?)\n</code></pre> <p>Score will keep a running total of a player score across games, again a simple integer value.</p> <pre><code>(spec/def ::score int?)\n</code></pre> <p>A player is represented by a hash-map that contains their name, score and the hand they are currently dealt.  The hand is a collection of tuples representing a playing card.</p> <pre><code>(spec/def ::player\n          (spec/keys\n            :req [::name ::score ::dealt-hand]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#game-deck-specs","title":"Game deck specs","text":"<p>A card game has a deck of 52 cards, one card for each combination of suit and rank.</p> <p>The size of the card deck changes over the course of a game, so the deck can contain any number of cards.  The deck must contain only cards to be valid.</p> <pre><code>(spec/def ::card-deck (spec/* ::playing-card))\n</code></pre> <p>At this stage in the design, a card game can have any number of players</p> <pre><code>(spec/def ::players (spec/* ::player))\n</code></pre> <p>A game is represented by a hash-map with a collection of players and a card deck</p> <pre><code>(spec/def ::game (spec/keys :req [::players ::card-deck]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#generative-data-from-specifications","title":"Generative data from Specifications","text":"<p>Clojure spec can generate random data which conforms to a specification, highly useful in testing Clojure code with a wide variety of values.</p> <ul> <li><code>clojure.spec.alpha/gen</code> returns a generator for the given specification.</li> <li><code>clojure.spec.gen.alpha/generate</code> takes that generator and creates a random value that conforms to the specification.</li> <li><code>clojure.spec.gen.alpha/sample</code> will generate a collection of random values that each conform to the specification.</li> </ul> <p>Require the clojure spec namespaces to make use of their functions.</p> <pre><code>(ns practicalli.card-game.clj\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]))\n\n(spec/def ::suits #{:clubs :diamonds :hearts :spades})\n(spec/def ::rank #{:ace 2 3 4 5 6 7 8 9 10 :jack :queen :king})\n</code></pre> <p>To generated data based on a specification, first get a generator for a given spec,</p> <pre><code>(spec/gen ::suits)\n</code></pre> <p><code>generate</code> will return a value using the specific generator for the specification.</p> <pre><code>(spec-gen/generate (spec/gen ::suits))\n</code></pre> <p><code>sample</code> will generate a number of values from the given specification</p> <pre><code>(spec-gen/sample (spec/gen ::rank))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#card-game-data","title":"Card Game data","text":"<p>Generate a random value for the <code>::player</code> specification</p> <pre><code>(spec-gen/generate (spec/gen ::player))\n</code></pre> Example <p>Expected output from <code>generate</code> ```clojure</p> <p>```</p> <p>Generate a random value for the <code>::game</code> specification</p> <pre><code>(spec-gen/generate (spec/gen ::game))\n</code></pre> <p>Generate a collection of random values that each conform to the specification.</p> <pre><code>(spec-gen/sample (spec/gen ::game))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#practicallispec-generative-testing","title":":practicalli.spec-generative-testing","text":"<p>{:name \"Yp34KE63vAL1eriKN4cBt\",  :score 225,  :dealt-hand ([9 :hearts] [4 :clubs] [8 :hearts] [10 :clubs] [:queen :spades] [3 :clubs] [6 :hearts] [8 :hearts] [7 :diamonds] [:king :spades] [:ace :diamonds] [2 :hearts] [4 :spades] [2 :clubs] [6 :clubs] [8 :diamonds] [6 :spades] [5 :spades] [:queen :clubs] [:queen :hearts] [6 :spades])}</p>"},{"location":"clojure-spec/projects/card-game/#function-specifications","title":"Function Specifications","text":"<p>A function specification can contain a specification for the arguments, the return values and the relationship between the two.</p> <p>The specifications for the function may be composed from previously defined data specifications.</p> <pre><code>(ns practicalli.card-game\n  (:require [clojure.spec.alpha :as spec]\n            [clojure.spec.gen.alpha :as spec-gen]\n            [clojure.spec.test.alpha :as spec-test]))\n\n(spec/def ::suit #{:clubs :diamonds :hearts :spades})\n(spec/def ::rank (into #{:jack :queen :king :ace} (range 2 11)))\n(spec/def ::playing-card (spec/tuple ::rank ::suit))\n(spec/def ::dealt-hand (spec/* ::playing-card))\n\n(spec/def ::name string?)\n(spec/def ::score int?)\n(spec/def ::player (spec/keys :req [::name ::score ::dealt-hand]))\n(spec/def ::card-deck (spec/* ::playing-card))\n(spec/def ::players (spec/* ::player))\n(spec/def ::game (spec/keys :req [::players ::card-deck]))\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#function-definition","title":"Function definition","text":"<p>The card game application has three functions to start with.</p> <pre><code>(defn regulation-card-deck\n  \"Generate a complete deck of playing cards\"\n  [{:keys [::deck ::players] :as game}]\n  (apply + (count deck)\n         (map #(-&gt; % ::delt-hand count) players)))\n</code></pre> <p>At the start of function design, the algorithm may still be undefined.  Using the specifications and generators mock data can be returned as a placeholder.</p> <pre><code>(defn deal-cards\n  \"Deal cards to each of the players\n   Returns updated game hash-map\"\n  [game]\n  (spec-gen/generate (spec/gen ::game)))\n</code></pre> <pre><code>(defn winning-player\n  \"Calculate winning hand by comparing each players hand\n  Return winning player\"\n  [players]\n  (spec-gen/generate (spec/gen ::player)))\n</code></pre> Example <p>The expected form of a player won game:</p> <pre><code>  #:practicalli.player-won\n  {:name      \"Jenny Nada\",\n   :score     225,\n   :dealt-hand [[9 :hearts] [4 :clubs] [8 :hearts] [10 :clubs] [:queen :spades]]}\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#spec-definitions","title":"Spec definitions","text":"<p>Define a function specification for the <code>deal-cards</code> function</p> <ul> <li>argument must be of type <code>::game</code></li> <li>return type is <code>::game</code></li> <li>function applies arguments to a game and returns the game</li> </ul> <pre><code>(spec/fdef deal-cards\n  :args (spec/cat :game ::game)\n  :ret ::game\n  :fn #(= (regulation-card-deck (-&gt; % :args :game))\n          (regulation-card-deck (-&gt; % :ret))))\n</code></pre> <p>Define a function specification for the <code>winning-player</code> function</p> <ul> <li>argument must be of type <code>::players</code></li> <li>return type is <code>::players</code></li> </ul> <pre><code>(spec/fdef winning-player\n  :args (spec/cat :players ::players)\n  :ret ::player)\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#instrument-functions","title":"Instrument functions","text":"<p>Instrumenting functions will wrap a function definition and check the arguments of any call to the instrumented function.</p> <pre><code>(spec-test/instrument `deal-cards)\n</code></pre> <p>Calling the <code>deal-cards</code> function with an incorrect argument returns an error that describes where in the specification the error occurred.</p> <pre><code>(deal-cards \"fake game data\")\n</code></pre> <p>Error in an easier to read format</p> <pre><code>ERROR: #error\n {:message \"Call to #'practicalli.card-game/deal-cards did not conform to spec:\\n\\\n \"fake game data\\\" - failed:\n map? in: [0] at: [:args :game] spec: :practicalli.card-game/game\\n\",\n :data {:cljs.spec.alpha/problems\n [{:path [:args :game],\n   :pred cljs.core/map?,\n   :val \"fake game data\",\n   :via [:practicalli.card-game/game :practicalli.card-game/game],\n   :in [0]}],\n :cljs.spec.alpha/spec #object[cljs.spec.alpha.t_cljs$spec$alpha17968],\n :cljs.spec.alpha/value (\"fake game data\"),\n :cljs.spec.alpha/args (\"fake game data\"),\n :cljs.spec.alpha/failure :instrument}}\n</code></pre>"},{"location":"clojure-spec/projects/card-game/#organizing-function-instrumentation","title":"Organizing function instrumentation","text":"<p>Instrumenting functions creates a wrapper around the original function definition.</p> <p>When you change the function definition and evaluate the new code, it replaces the instrumentation of the function.  Therefore each time a function is redefined it should be instrumented.</p> <p>There is no specific way to manage instrumenting a function, however, a common approach is to define a collection of functions to instrument, then use a helper function to instrument all the functions at once.</p> <p>Bind a name to the collection of function specifications.</p> <pre><code>(def ^:private function-specifications\n  [`card-game/deal-cards\n   `card-game/winning-player])\n</code></pre> <p>Define a simple helper function to instrument all the functions in the collection.</p> <pre><code>(defn instrument-all-functions\n  []\n  (spec-test/instrument function-specifications))\n</code></pre> <p>Refactoring the code may involve a number of changes benefit from instrumentation being switched off until its complete.  The <code>unstrument</code> function will remove instrumentation from all the functions in the collection.</p> <pre><code>(defn unstrument-all-functions\n  []\n  (spec-test/unstrument function-specifications))\n</code></pre> <p>Koacha Test Runner can include functional specifications</p> <p>Koacha test runner can manage the testing of function specifications and is especially useful for managing unit level testing with specifications.</p>"},{"location":"clojure-spec/testing/","title":"Testing with Specifications","text":""},{"location":"clojure-spec/testing/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"clojure-spec/testing/#during-development","title":"During development","text":"<p>Create specifications for data and functions</p> <p>Selectively instrument function definitions to check function call arguments against the function specification.</p> <ul> <li>clojure.spec.test.alpha/instrument - check fdef :args</li> </ul>"},{"location":"clojure-spec/testing/#unit-and-integration-testing","title":"Unit and integration testing","text":"<p>Add specification checks along with unit testing and integration testing to provide a very wide range of data values to be tested (with a minimal amount of code).</p> <ul> <li>clojure.spec.test.alpha/check - use :args to generate tests to check fdef :ret and :fn</li> </ul> <p>run a suite of spec-generative tests on an entire ns with <code>check</code>.  Just one namespace per <code>check</code> expression?</p> <p>control the number of values check creates for each check expression.  As the default is 1000 the checks can take a noticeable time to run (see practicalli/spec-generative-testing)</p> <p>Many built-in generators for <code>clojure.core</code> data predicates</p> <p>composite specifications can build generators upon predicate generators.</p> <p>Pass generator-returning functions to spec, supplying generators for things spec does not know about. Pass an override map to <code>gen</code> in order to supply alternative generators for one or more sub-paths of a spec.</p> <p>Define your own generators</p>"},{"location":"clojure-spec/testing/#at-run-time","title":"At run time","text":"<p>Use specifications for run time checking, typically using <code>conform</code> and <code>valid?</code> functions.</p> <p>Specification are typically the minimal checks required for the system, compared to more extensive checks during test and system integration.</p> <p>Create lightweight private specifications for tests that run in the production environment.</p>"},{"location":"clojure-spec/testing/checking%20arguments/","title":"Checking arguments in function calls with specifications","text":""},{"location":"clojure-spec/testing/checking%20arguments/#instrument-functions-during-development","title":"Instrument functions during development","text":"<p>Instrumenting a function enables the checking of arguments in a function call against the specification defined in an <code>fdef</code> definition of the same name.</p> <pre><code>(clojure.spec.test.alpha/instrument `function-name)\n</code></pre> <p>Instrumenting a function swaps the function definition var with a wrapped version of the function definition which includes tests the <code>:args</code> spec from the <code>fdef</code> expression.</p> <p><code>unstrument</code> returns the function definition to the original form and tests for that function are no longer run.</p>"},{"location":"clojure-spec/testing/checking%20arguments/#unit-specification-testing","title":"Unit (Specification) testing","text":"<p>You can generate data for interactive testing with gen/sample.</p>"},{"location":"coding-challenges/","title":"Coding Challenges for Clojure","text":"<p>Coding challenges are an excellent way to start learning a new language.  The challenges allow you to focus on the language and not be concerned about the more general engineering aspects of software development.</p> <p>Challenges are there to explore a language and practice your understanding of how to assemble working code.  It is recommended to try different approaches to solving a challenges and even repeat the same challenges at a later date and see what additional approaches you have learned.</p> <p>Exercism.io and 4Ever-Clojure are highly recommended starting point for learning Clojure and does not require any installation or setup.  4Ever-Clojure is a new implementation of 4Clojure.com.</p>"},{"location":"coding-challenges/#practicalli-challenges","title":"Practicalli Challenges","text":"<p>Challenge that can be solved in a few hours (or less).  Use a Clojure REPL connected editor to help solve these challenges. </p> <ul> <li>Simple Projects</li> <li>TDD Code Kata</li> </ul>"},{"location":"coding-challenges/#approach-to-solving-challenges","title":"Approach to solving challenges","text":"<p>Take a few minutes to digest the description of the challenge and make notes.</p> <p>Identify the simplest possible thing to do, solving the problem in many small pieces which encourages experimentation</p> <ul> <li>experiment, write code and evaluate to see what it does (optionally create a comment with the result)</li> <li>use a rich comment <code>(comment ,,,)</code> to capture multiple ideas and designs, even failed experiments can be useful (separates experiments from working code)</li> <li>continually evaluate code as expressions are written, to ensure their behaviour is understood (try different argument values for functions)</li> <li>try different shapes of data</li> <li>transform data shapes to keep function definitions simpler</li> </ul> <p>Once there is a working solution, refactor or try different approaches and evaluate the merit of alternative solutions</p>"},{"location":"coding-challenges/#challenge-websites","title":"Challenge websites","text":"<p>A local Clojure development environment supports solving challenge websites, e.g Clojure CLI and a Clojure REPl connected editor </p> Challenge website Description Requirements 4Ever-Clojure Learning the core functions of the Clojure language Web Browser Exercism Coding exercises with mentor support Web Browser &amp; Exercim CLI ClojureScript Koans Interactive exercises in a web browser Web Browser Advent of Code Yearly coding challenge with a seasonal theme Clojure aware editor CodeWars Mostly math-based coding challenges with Clojure variants Web Browser"},{"location":"coding-challenges/advent-of-code/","title":"Advent Of Code","text":""},{"location":"coding-challenges/advent-of-code/#advent-of-code","title":"Advent Of Code","text":"<p>Advent of Code is the annual coding challenge with a festive theme.  Each day there is a new challenge in two parts, the first fairly easy the second a little more involved.  The challenges are an investment of your time to complete them all, although even trying just a few is enough to help you think in different ways.</p> <p>Every programming language requires regular practice to maintain your skills.  A full time developer role gives lots of opportunities to practice every day, however, its often focused in around solving problems within a specific business domain, with little time to explore others.  The Advent of Code puts you in a different domain, so its great for extending your coding experiences.</p> <p>Solving challenges in a different language is another great way to extend your experiences, so here are some tips and examples for solving the advent of code in Clojure.</p>"},{"location":"coding-challenges/advent-of-code/#solving-challenges","title":"Solving challenges","text":"<ul> <li>Keep the solution as simple as possible.  Its very easy to over-complicate the solution and end up simply confusing yourself.</li> <li>Don't try and make the perfect solution.  Write something that works, this will give you a nice ego boost.  Then you can experiment with the code and see if you can improve your approach.</li> <li>Break down the problem into the simplest thing you can solve first.  Trying to solve a problem all at once will quickly have you going around in circles.</li> <li>Keep all the code and make notes.  I use a a design journal in my projects to document my thinking process, capture decisions that worked and those that didn't work for this project.  The journal is a great way to cement learning from solving the challenge.</li> <li>Challenges are only accessible from their day of the month onwards.  There is a count-down clock displayed on the next challenge to open, so you know when it will be available.  Don't feel pressured to keep up with the challenges though, enjoy the experience and have fun, you will learn more that way.</li> </ul>"},{"location":"coding-challenges/advent-of-code/#coding-video","title":"Coding video","text":"<p>A video guide to solving the first challenge of Advent of Code from 2018, trying out different solutions at increasing levels of abstraction.  With each level of abstraction it helps to think in a more functional way.</p> <p> </p>"},{"location":"coding-challenges/advent-of-code/#creating-a-project-for-the-challenge","title":"Creating a project for the challenge","text":"<pre><code>clojure -T:project/create :template lib practicalli.advent-of-clojure-code/2019\n</code></pre> <p>Create a new Clojure file for each of the daily challenges.  It makes sense to keep both parts of each day in the same file.</p> <p>Practicalli Advent Of Code solutions repository</p> <p>practicalli/advent-of-clojure-code-2019</p>"},{"location":"coding-challenges/advent-of-code/#useful-resources-and-examples","title":"Useful Resources And Examples","text":"<p>Videos and code solutions to many challenges from 2019 and past years.</p> <ul> <li>fdlk/advent-2019 - example Clojure solutions to the advent of code</li> <li>Awesome Advent Of Code - a collection of solutions in various languages</li> <li>Advent of Code 2018 video walk-through of Clojure solutions by Tim Pote and GitHub repository</li> </ul> <p>#adventofcode channel in the Clojurians slack channel discusses challenges and solutions, especially during December when the challenge takes place.</p>"},{"location":"coding-challenges/koans/","title":"ClojureScript Koans","text":"<p>Koans are a collection of small challenges that slowly increase in complexity.  They are similar to the 4Clojure challenges in scope.</p>"},{"location":"coding-challenges/koans/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"coding-challenges/4clojure/","title":"Coding Challenges: 4Clojure","text":"<p>4Ever-Clojure Challenges Website</p> <p>4Ever-Clojure is a simple website with 150 challenges to help discover the functions built-in to the Clojure language, the Clojure API.</p> <p>The website is self-contained with nothing to install, simply paste in the missing code and run the tests.  One piece of code should solve all the tests for that challenge.</p> <p>The Problem List shows the challenges categorized by experience level required, (Elementary, Easy, Medium, Hard) to solve them.  Start with the easiest problem or work your way through the challenges in any order you wish.  The Status column tracks your progress thorugh the challenges.</p> <p>Select the name of a challenge to see the description and one or more code tests that must pass.</p> <p>Enter the code that should be inserted where the <code>__</code> double underscore characters are.</p> <p>Press the Run button to see if the code satisfies the tests</p> <p>A dialog box is displayed showing how many tests have passed and failed</p> <p>Start learning the Clojure API</p> <p>There are over 600 functions in the <code>clojure.core</code> namespace alone, with additional functions in many other namespaces that make up the https://clojure.github.io/clojure/.  It is not required to learn all these functions to be productive in Clojure.</p> 4ever-clojure replaces 4Clojure <p>4Ever-Clojure is a new implementation of 4Clojure.com which has now been decommissioned</p>"},{"location":"coding-challenges/4clojure/#help-completing-the-challenges","title":"Help completing the challenges","text":"<p>Look at the Clojure Cheatsheet and Clojure API for an understanding of what functions are available in the core of the Clojure language.</p> <p>Search directly in ClojureDocs for functions.  Each function has a page that describes the function, shows the arguments it takes and provides many examples of its use.  At the end of the page are related functions too.</p> <p>Practicalli Code walk-through and solution journal</p> <p>practicalli/four-clojure code journals for the first 60 challenges contains a design journal showing how each challenge was solved and additional refactor or alternative approaches to the solution.</p> <p>Practicalli 4Clojure guides playlist provides video walk-through of the first 64 challenges, again with alternative solutions where relevant.</p> <p>An Internet search of <code>clojure topic</code>, where <code>topic</code> is a name of the thing you want to do, should return many examples of functions that could be useful to solving the challenge.  Or</p> <p>Help from the community</p> <p>Clojure community - getting help covers several sources of help from the Clojure community.</p>"},{"location":"coding-challenges/4clojure/#using-let-and-anonymous-functions","title":"Using let and anonymous functions","text":"<p>The solution submitted should be a single form, which is inserted in the test code where the <code>__</code> underscore placeholder is.  It is therefore not possible to define data with <code>def</code> or a separate function with <code>defn</code> to support the submitted solution.</p> <p>Use the anonymous function, <code>(fn [])</code>, to define behaviour.</p> <pre><code>(fn [value1 value2]\n  (* value1 value2))\n</code></pre> <p>Use let to bind a name to a value, so that value can be re-used throughout the expression.  <code>let</code> is also useful for breaking the algorithm into smaller pieces, making it easier to solve the challenge.</p> <pre><code>(let [name value]\n  (* 2 value (/ value 4) (+ value 3)))\n</code></pre> <p>It is common to combine <code>fn</code> and <code>let</code> to solve the challenges as they grow in complexity</p> <pre><code>(fn fibonacci [length-of-series]\n  (let [fib [1 1]]\n    (if (&lt; (count fib) length-of-series)\n      \"iterate... to implement\"\n      fib)))\n</code></pre> <ul> <li>fn - ClojureDocs</li> <li>let - ClojureDocs</li> <li>Fibonacci sequence guide - practicalli</li> </ul>"},{"location":"coding-challenges/4clojure/#my-function-is-not-working","title":"My function is not working","text":"<p>4Ever Clojure uses babashka/sci project to evaluate code on a JavaScript host.  Whist this should cover 99.9% of the Clojure API there may be some code that works in a Clojure (JVM) REPL that is not supported.</p> <p>Try the code in a Clojure REPL or create a Clojure project using the latest version of Clojure (1.11.x).</p>"},{"location":"coding-challenges/4clojure/#references","title":"References","text":"<ul> <li>4Ever-Clojure</li> <li>Clojure Cheatsheet - Clojure.org</li> <li>Clojure API - Clojure.org</li> <li>practicalli/four-clojure code journals for the first 60 challenges</li> <li>4Clojure video guides by Practicalli</li> <li>Clojure Core Library - ClojureDocs</li> <li>Clojure, The Essential Reference - Renzo Bogatti - Manning book published in 2020</li> </ul>"},{"location":"coding-challenges/codewars/","title":"CodeWars","text":"<p>Coding challenges in various languages with ranking scoreboard, experience levels and voting on solutions.  Many of the challenges tend toward mathematics, so may require some background research before solving them.</p>"},{"location":"coding-challenges/codewars/#requirements","title":"Requirements","text":"<p>Codewars is a web browser based system in which you can write code and run tests.  Sample unit tests are provided with each challenge, so its all self-contained.</p> <p>Create a free account and select the language you wish to attempt challenges in.  Two simple coding tests will need to be completed in order to access that specific language.</p>"},{"location":"coding-challenges/codewars/#challenges-dashboard","title":"Challenges Dashboard","text":"<p>After logging in, the dashboard suggests a challenge for you at a suitable level.  8 kyu is the easiest level, the smaller the number the harder the challenge.</p> <p></p>"},{"location":"coding-challenges/codewars/#tackling-a-challenge","title":"Tackling a challenge","text":"<p>Read the instructions and take a look at the sample tests.</p> <p>Many of the challenges have only a very basic explanation, so always review the sample unit tests to help with the understanding.  The sample tests are not necessarily the full suite of tests run when testing your solution, so there may be undocumented edge cases to solve</p> <p>The source and test code can be copied into a new project, as has been done with the practicalli/codewars-guides solutions</p> <pre><code>clojure -M:new lib practicalli/readability-is-king\n</code></pre> <p>Update the solution window with your solution and use the TEST button to run the sample unit tests.</p> <p>The ATTEMPT button will run all the unit tests for the challenge, which may be more than the sample tests.  If the attempt passes all the tests then the solution can be submitted an other solutions reviewed.</p> <p></p>"},{"location":"coding-challenges/codewars/#tracking-progress","title":"Tracking progress","text":"<p>View your profile page to track your progress and revisit kata challenges already completed.</p> <p></p>"},{"location":"coding-challenges/codewars/#references","title":"References","text":"<p>practicalli/codewars-guide - a repository of code solutions to CodeWars challenges, each challenge is its own Clojure CLI (deps.edn) project.</p> <p> YouTube: CodeWars video guides Unofficial Free Code Camp Clojure Challenges</p>"},{"location":"coding-challenges/exercism/","title":"Exercism Challenges","text":"<p> Exercism Clojure Track</p> <p> Exercism is a learning platform for multiple programming languates (currently 67) which combines carefully crafted coding challenges and mentors who review and advise on solutions.</p> <p>Solve challenges via the built-in Exercism editor.</p> <p></p> <p>Or download each exercise locally using the  Exercism CLI, providing a  Clojure CLI configured project with a test runner.</p> <p>Use the  Exercism CLI to submit a solution for metor feedback.</p> Exercism embdedded Clojure editor <p>The Exercisim Clojure editor is powered by  babashka/sci</p>"},{"location":"coding-challenges/exercism/#clojure-track","title":"Clojure Track","text":"<p>All the challenges are groups into specific  language tracks, including the  Clojure track</p> <p>Join the language track to be presented with available challenges and progress through that specific track.</p> <p></p>"},{"location":"coding-challenges/exercism/#working-locally","title":"Working Locally","text":"<p> Exercism Guide to working locally</p> <p>Follow the  Practicalli Clojure CLI Install steps (Exercism includes a similar  Clojure CLI install guide)</p> <p>The  Exercism CLI can download a Clojure project containing the code for a specific challeng and submit the code back to exercism to confirm if the tests have passed and complete the challenge (or get feedback from a mentor).</p> Each challenge shows the download and submit commands <p>Each Exercise page shows the command to download the code for that specific exercise, which is of the form <pre><code>exercism download --exercise=exercise-name --track=clojure\n</code></pre></p> <p>Open the project source code downloaded from Exercism in a  preferred Clojure editor and write a solution to solve the exercise.</p> <p><code>clojure -X:test</code> command in the root of the downloaded project will run the tests supplied by the exercise</p> Practicalli Test Runner aliases <p><code>clojure -X:test/run</code> runs the Kaocha test runner from the  Practicalli Clojure CLI Config</p> <p><code>clojure -X:test/watch</code> will automatically re-run tests when file changes are detected.</p> <p> Clojure test runner covers test runner options in more detail.</p> <p>Once the tests pass and you are happy with the solution, submit it to the Exercism website</p> <pre><code>exercism submit /path/to/src-file\n</code></pre>"},{"location":"coding-challenges/exercism/#repl-workflow","title":"REPL Workflow","text":"<p>Use a REPL workflow to get instant feedback on code written to make the unit test assersions pass.</p> Terminal UIEditor connected REPL <p>Start a REPL via a Terminal UI in the root of the Exercism project</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Open the project in a  Clojure aware editor and connect to the REPL process.</p> <p>Open the project in a  Clojure aware editor and start a Clojure REPL, e.g. jack-in</p> <p>Use a rich <code>comment</code> to experiment with clojure expressions that help move towards a solution, typically solving one unit test at a time. This separates experimental code from finished designs.</p> <pre><code>(comment \n  ;; experiment with clojure code \n  ;; evaluate expressions in the Clojure editor\n  ;; and see the evalaution results inline\n)\n</code></pre> <p>Disable Linter rules</p> <p>Disable Linter rules within the <code>comment</code> expression that are not useful for REPL experiments.</p> <p>It is common to have several implmentations of a function with the same name, so <code>:redefined-var</code> is disabled.</p> <p>Functions defined in the REPL experments are not ment to be used publicly (until they are copied/moved out of the comment form), so <code>:clojure-lsp/unused-public-var</code> lint rule is disabled <pre><code>#_{:clj-kondo/ignore [:redefined-var :clojure-lsp/unused-public-var]}\n(comment\n  ,,,\n)\n</code></pre></p>"},{"location":"coding-challenges/exercism/#support","title":"Support","text":"<p>Mentors on the Exercism website will provide a review of your submissions and you can switch between mentor and practice modes as you prefer.</p> <p> practicalli/exercism-clojure-guides contains a design journal of solutions to several Clojure exercises.</p> <p>Ask for advice in the #exercism or #beginners channels of the Clojurians Slack community.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/","title":"Nucleotide Count","text":"<p> Clojure Track: Nucleotide Count</p> <p>Given a string representing a DNA sequence, count how many of each nucleotide is present.</p> <p>If the string contains characters other than A, C, G, or T then an error should be throw.</p> <p>Represent a DNA sequence as an ordered collection of nucleotides, e.g. a string of characters such as \"ATTACG\".</p> <pre><code>\"GATTACA\" -&gt; 'A': 3, 'C': 1, 'G': 1, 'T': 2\n\"INVALID\" -&gt; error\n</code></pre> <p>DNA Nucleotide names</p> <p><code>A</code> is Adenine, <code>C</code> is Cytosine, <code>G</code> is Guanine and <code>T</code> is Thymine</p> <p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#create-the-project","title":"Create the project","text":"<p>Download the Nucleotide Count exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=nucleotide-count --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#starting-point","title":"Starting point","text":"<p>Unit test code calls functions from the <code>src</code> tree which must exist with the correct argument signature for the unit test code to compile successfully.</p> <p>Reviewing each assertion in the unit test code identifies the function definitions required.</p> Exercism Unit Tests <pre><code>(ns nucleotide-count-test\n  (:require [clojure.test :refer [deftest is]]\n            nucleotide-count))\n\n(deftest empty-dna-strand-has-no-adenosine\n  (is (= 0 (nucleotide-count/count-of-nucleotide-in-strand \\A, \"\"))))\n\n(deftest empty-dna-strand-has-no-nucleotides\n  (is (= {\\A 0, \\T 0, \\C 0, \\G 0}\n         (nucleotide-count/nucleotide-counts \"\"))))\n\n(deftest repetitive-cytidine-gets-counted\n  (is (= 5 (nucleotide-count/count-of-nucleotide-in-strand \\C \"CCCCC\"))))\n\n(deftest repetitive-sequence-has-only-guanosine\n  (is (= {\\A 0, \\T 0, \\C 0, \\G 8}\n         (nucleotide-count/nucleotide-counts \"GGGGGGGG\"))))\n\n(deftest counts-only-thymidine\n  (is (= 1 (nucleotide-count/count-of-nucleotide-in-strand \\T \"GGGGGTAACCCGG\"))))\n\n(deftest validates-nucleotides\n  (is (thrown? Throwable (nucleotide-count/count-of-nucleotide-in-strand \\X \"GACT\"))))\n\n(deftest counts-all-nucleotides\n  (let [s \"AGCTTTTCATTCTGACTGCAACGGGCAATATGTCTCTGTGTGGATTAAAAAAAGAGTGTCTGATAGCAGC\"]\n    (is (= {\\A 20, \\T 21, \\G 17, \\C 12}\n           (nucleotide-count/nucleotide-counts s)))))\n</code></pre> <p>Function definitions required to compile unit test code</p> src/nucleotide_count.clj<pre><code>(ns nucleotide-count)\n\n(defn count-of-nucleotide-in-strand\n  \"Count how many of a given nucleotide is in a strand\"\n  [nucleotide strand])\n\n(defn nucleotide-counts\n  \"Count all nucleotide in a strand\"\n  [strand])\n</code></pre>"},{"location":"coding-challenges/exercism/nucleotide-count/#making-the-tests-pass","title":"Making the tests pass","text":"<p>Select one assertion from the unit tests and write code to make the test pass.</p> <p>Experiment with solutions in the <code>comment</code> form and add the chosen approach to the respective function definition.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#counting-nucleotides","title":"Counting nucleotides","text":"<p>Use test data from the unit test code, e.g. <code>\"GGGGGTAACCCGG\"</code></p> <p>How often does a nucleotide appear</p> <p>Example</p> <pre><code>  (map\n    #(if (= % \\A) 1 0)\n    \"GGGGGTAACCCGG\")\n</code></pre> <p>Add the result to get the total count</p> <p>Example</p> <pre><code>  (count\n   (map\n     #(if (= % \\A) 1 0)\n     \"GGGGGTAACCCGG\"))\n</code></pre> <p>Is there a more elegant way?</p> <p>When only the matching nucleotide is in the strand, then all the elements of the strand can be counted.</p> <p><code>filter</code> the DNA strand with a predicate function (returns true/false) that returns only the matching nucleotide.</p> <p>Example</p> <pre><code>  (filter #(= % \\A) valid-nucleotides))\n</code></pre> <p>;; Count the elements in the returned sequence for the total</p> <p>Example</p> <pre><code>  (count\n   (filter #(= % \\A) valid-nucleotides))\n</code></pre> <p>Add this code into the starting function</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#run-unit-tests","title":"Run unit tests","text":"<p>Run the unit tests to see if they pass.  x should pass, x should fail.</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#nucleotide-occurances","title":"Nucleotide occurances","text":"<p>Count the occurances</p> <p>\"GGGGGTAACCCGG\"</p> <pre><code>   (count\n     (filter (fn [nucleotide] (= nucleotide \\A))\n             \"GGGGGTAACCCGG\"))\n</code></pre> <p>Define the data</p> <pre><code>  (def valid-nucleotides\n    \"Characters representing valid nucleotides\"\n    [\\A \\C \\G \\T])\n</code></pre> <p>Exception handling required</p> <pre><code>(throw (Throwable.)) if nucleotide is \\X\n</code></pre> <p>Or use a predicate with some (some element? in the sequence)</p> <pre><code>  (some #(= \\G %) valid-nucleotides)\n\n  (some #{\\G} valid-nucleotides)\n</code></pre> <pre><code>  (defn count-of-nucleotide-in-strand\n    [nucleotide strand]\n    (if (some #(= nucleotide %) valid-nucleotides)\n      (count\n       (filter #(= nucleotide %)\n               strand))\n      (throw (Throwable.))))\n\n  (count-of-nucleotide-in-strand \\T \"GGGGGTAACCCGG\")\n</code></pre> <p>Design the second function</p> <p>How often does a nucleotide appear</p> <pre><code>  (map\n    #(if (= % \\A) 1 0)\n    valid-nucleotides)\n</code></pre> <p>Add the result to get the total count</p> <p>Is there a more elegant way?</p> <pre><code>  (filter #(= % \\A) valid-nucleotides)\n</code></pre> <p>Count the elements in the returned sequence for the total</p> <p>Design the second function</p> <p>How often does a nucleotide appear</p> <p>NOTE: zero must be returned when there are no appearences</p> <p>Return value always in the form</p> <pre><code>  {\\A 20, \\T 21, \\G 17, \\C 12}\n</code></pre>"},{"location":"coding-challenges/exercism/nucleotide-count/#hammock-time","title":"Hammock time...","text":"<ul> <li>How often does something appear,</li> <li>how frequenct is it?</li> <li>Is there a clojure standard library for that (approx 700 functions), review https://clojure-docs.org/</li> </ul> <pre><code>  (frequencies \"GGGGGAACCCGG\")\n</code></pre> <p>If there are missing nucleotides then there is no answer</p> <p>What if there is a starting point</p> <pre><code>  {\\A 0 \\C 0 \\G 0 \\T 0}\n</code></pre> <p>;; Then merge the result of frequencies</p> <pre><code>  (merge {\\A 0 \\C 0 \\G 0 \\T 0}\n         (frequencies \"GGGGGAACCCGG\"))\n</code></pre> <p>Update the function definition and run tests</p>"},{"location":"coding-challenges/exercism/nucleotide-count/#solutions","title":"Solutions","text":"<p>There are many ways to solve a challenge and there is value trying different approaches to help learn more about the Clojure language.</p> <p>The following solution includes <code>filter</code> and <code>frequencies</code> functions which are commonly used functions from the Clojure standard library.</p> <p>Example Solution</p> src/nucleotide_count.clj<pre><code>(ns nucleotide-count)\n\n(def valid-nucleotides\n    \"Characters representing valid nucleotides\"\n    [\\A \\C \\G \\T])\n\n(defn count-of-nucleotide-in-strand\n  [nucleotide strand]\n  (if (some #(= nucleotide %) valid-nucleotides)\n    (count\n     (filter #(= nucleotide %)\n             strand))\n    (throw (Throwable.))))\n\n(defn nucleotide-counts\n  \"Count all nucleotide in a strand\"\n  [strand]\n  (merge {\\A 0 \\C 0 \\G 0 \\T 0}\n         (frequencies \"GGGGGAACCCGG\")))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/","title":"Exercise: RNA Transcription","text":"<p> Clojure Track: Nucleotide Count</p> <p>Given a DNA strand, return its RNA complement (per RNA transcription).</p> <p>Both DNA and RNA strands are a sequence of nucleotides.</p> <p>The four nucleotides found in DNA are adenine (A), cytosine (C), guanine (G) and thymine (T).</p> <p>The four nucleotides found in RNA are adenine (A), cytosine (C), guanine (G) and uracil (U).</p> <p>Given a DNA strand, its transcribed RNA strand is formed by replacing each nucleotide with its complement:</p> <ul> <li>G -&gt; C</li> <li>C -&gt; G</li> <li>T -&gt; A</li> <li>A -&gt; U</li> </ul> <p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#create-the-project","title":"Create the project","text":"<p>Download the RNA transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=rna-transcription --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#designing-the-solution","title":"Designing the solution","text":"<p>To convert a collection of values, define a hash-map where the keys are the initial DNA values and the hash-map values are the transformed RNA values.  Using a hash-map in this way is often termed as a dictionary.</p> <p>A string is used as a collection of character values by many of the functions in <code>clojure.core</code>.  The dictionary uses characters for its keys and values.</p> <pre><code>{\\G \\C \\C \\G \\T \\A \\A \\U}\n</code></pre> <p>Use the <code>map</code> function to pass the dictionary over the dna string (collection of characters) to create the RNA transcription.</p> <p>Use an anonymous function to wrap the dictionary and pass each a character (nucleotide) from the DNA string in turn.</p> <pre><code>(defn to-rna\n  [dna]\n  (map (fn [nucleotide] (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide))\n       dna))\n</code></pre> <pre><code>(to-rna \"GCTA\")\n</code></pre> <p>The result is returned as a sequence of characters.</p> <p>Refactor the <code>to-rna</code> function and add <code>clojure.string/join</code> to return the RNA value as a string</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide] (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide))\n         dna)))\n</code></pre> <p>Now the function returns a string rather than a collection of characters.</p> <pre><code>(to-rna \"GCTA\")\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#throwing-an-assertion-error-for-incorrect-nucleotide","title":"Throwing an assertion error for incorrect nucleotide","text":"<p>In the Exercism test suite, one test checks for an AssertionError when an incorrect nucleotide is passed as part of the DNA string.</p> <pre><code>(deftest it-validates-dna-strands\n  (is (thrown? AssertionError (rna-transcription/to-rna \"XCGFGGTDTTAA\"))))\n</code></pre> <p>The <code>throw</code> function can be use to return any of the Java errors. An assertion error would be thrown using the following code</p> <pre><code>(throw (AssertionError. \"Unknown nucleotide\"))\n</code></pre> <p>Refactor the <code>to-rna</code> function to throw an assertion error if a nucleotide if found that is not part of the dictionary.</p> <p>An <code>if</code> function could be used with a conditional to check if each nucleotide is one of the keys in the dictionary and throw an AssertionError if not found.  This would mean consulting the dictionary twice, once for the conditional check and once for the conversion.</p> <p>Is there a way to consult the dictionary once for each nucleotide?</p> <p>The <code>get</code> function can return a specific not-found value when a key is not found in a map.</p> <p>What if the <code>throw</code> function is used as the not-found value in the <code>get</code> function?</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide ](get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide\n                               (throw (AssertionError. \"Unknown nucleotide\")) ))\n         dna)))\n</code></pre> <p>Unfortunately this approach will evaluate the throw expression regardless of if the nucleotide is found in the dictionary, so calling this version of the function always fails.</p> <p>The <code>or</code> function evaluate the first expression and if a true value is returned then any additional expressions are skipped over.</p> <p>If the first expression returns false or a falsey value, i.e. <code>nil</code>, then the next expression is evaluated.</p> <p>Proposed Solution</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide](or (get {\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide)\n                             (throw (AssertionError. \"Unknown nucleotide\"))))\n         dna)))\n</code></pre> <p>Call the <code>to-rna</code> function with a DNA string from the unit test code</p> <pre><code>(to-rna \"GCTA\")\n</code></pre> <p>The function should return <code>\"CGAU\"</code></p> <p>Call the <code>to-rna</code> function with a DNA string that contains an invalid nucleotide.</p> <pre><code>(to-rna \"GCXA\")\n</code></pre> <p>An <code>AssertionError</code> is thrown as the <code>X</code> character does not exist in the dictionary hash-map, so the <code>get</code> expression returns <code>nil</code>.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#refactor","title":"Refactor","text":"<p>Now the function is solving unit tests, minor adjustments can be made to streamline the code.</p>"},{"location":"coding-challenges/exercism/rna-transcription/#hash-map-as-function","title":"Hash map as function","text":"<p>A hash-map can be called as a function and takes a key as an argument.  This acts the same as the <code>get</code> function, returning the value  associated to a matching key, otherwise returning <code>nil</code> or the not-found value if specified.</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map (fn [nucleotide] (or ({\\G \\C \\C \\G \\T \\A \\A \\U} nucleotide)\n                              (throw (AssertionError. \"Unknown nucleotide\"))))\n         dna)))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#anonymous-function","title":"Anonymous function","text":"<p>The anonymous function, <code>fn</code>, has a terse form.</p> <p><code>#(* %1 %2)</code> is the same as <code>(fn [value1 value2] (+ value1 value2))</code></p> <p>This syntax sugar is often use with <code>map</code>, <code>reduce</code>, <code>apply</code> functions as the behaviour tends to be compact and of single use.</p> <p>If the function definition is more complex or used elsewhere in the namespace, then the <code>defn</code> function should be used to define shared behavior.</p> <p>Solution with anonymous function</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map #(or ({\\G \\C \\C \\G \\T \\A \\A \\U} %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#named-dictionary-data","title":"Named dictionary data","text":"<p>Replace the hard-coded hash-map by defining a name for the dictionary.</p> <p>Define a name to represent the dictionary data</p> <pre><code>(def dictionary-dna-rna {\\G \\C \\C \\G \\T \\A \\A \\U})\n</code></pre> <p>Refactor the <code>to-rna</code> function to use the dictionary by name.</p> <p>Solution using named dictionary data</p> <pre><code>(defn to-rna\n  [dna]\n  (clojure.string/join\n    (map #(or (dictionary-dna-rna %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna)))\n</code></pre>"},{"location":"coding-challenges/exercism/rna-transcription/#making-the-function-pure","title":"Making the function pure","text":"<p>Its beyond the scope of the Exercism challenge, however, its recommended to use pure functions where possible.</p> <p>A pure function only uses data from its arguments.</p> <p>Adding a dictionary as an argument to the <code>to-rna</code> function would be simple.</p> <p>Pure function approach</p> <pre><code>(defn to-rna\n  [dictionary dna]\n  (clojure.string/join\n    (map #(or (dictionary %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre> <p>With a dictionary as an argument the function is also more usable, as other dictionaries could be used with the function.</p> <p>The function would now be called as follows</p> <pre><code>(to-rna dictionary-dna-rna \"GTGAC\")\n</code></pre>"},{"location":"coding-challenges/exercism/space-age/","title":"Space Age","text":""},{"location":"coding-challenges/exercism/space-age/#topics-covered","title":"Topics covered","text":"<p>Code for this solution on GitHub</p> <p>practicalli/exercism-clojure-guides contains the design journal and solution to this exercise and many others.</p>"},{"location":"coding-challenges/exercism/space-age/#create-the-project","title":"Create the project","text":"<p>Download the RNA transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=rna-transcription --track=clojure\n</code></pre> <p>Use the REPL workflow to explore solutions locally</p> <p>Open the project in a Clojure aware editor and start a REPL, using a rich comment form to experiment with code to solve the challenge.</p>"},{"location":"coding-challenges/exercism/space-age/#challenge-introduction","title":"Challenge introduction","text":"<p>Given an age in seconds, calculate how old someone would be on:</p> <ul> <li>Earth: orbital period 365.25 Earth days, or 31557600 seconds</li> <li>Mercury: orbital period 0.2408467 Earth years</li> <li>Venus: orbital period 0.61519726 Earth years</li> <li>Mars: orbital period 1.8808158 Earth years</li> <li>Jupiter: orbital period 11.862615 Earth years</li> <li>Saturn: orbital period 29.447498 Earth years</li> <li>Uranus: orbital period 84.016846 Earth years</li> <li>Neptune: orbital period 164.79132 Earth years</li> </ul> <p>So if you were told someone were 1,000,000,000 seconds old, you should be able to say that they're 31.69 Earth-years old.</p>"},{"location":"coding-challenges/exercism/bob/","title":"Index","text":""},{"location":"coding-challenges/exercism/bob/#bob","title":"Bob","text":"<p>The Bob challenge involves writing a very basics example of a text parser, something that would be used for a text based adventure game.</p> <p>Bob is described as a lackadaisical teenager, so responses are very limited.  To create the Bob text parser we need to identify the rules that determine Bob's response.</p> <p>The instructions provide some basic rules:</p> <ul> <li>Bob answers 'Sure.' if you ask him a question.</li> <li>He answers 'Whoa, chill out!' if you yell at him.</li> <li>He answers 'Calm down, I know what I'm doing!' if you yell a question at him.</li> <li>He says 'Fine. Be that way!' if you address him without actually saying anything.</li> <li>He answers 'Whatever.' to anything else.</li> </ul> <p>It is important to also read through the supplied unit tests to elaborate on these rules.</p>"},{"location":"coding-challenges/exercism/bob/#create-the-project","title":"Create the project","text":"<p>Download the Bob transcription exercise using the exercism CLI tool</p> <pre><code>exercism download --exercise=bob --track=clojure\n</code></pre> <p>To use the Clojure CLI tool instead of Leiningen, create a <code>deps.edn</code> file containing an empty hash-map, <code>{}</code> and clone  Practicalli Clojure CLI Config to <code>~/.clojure/</code>.</p>"},{"location":"coding-challenges/exercism/bob/#rules-derived-from-the-unit-tests","title":"Rules derived from the Unit tests","text":"<p>Reviewing all the examples from the unit tests, there are 5 rules for the Bob parser</p> <p>These rules were discovered by searching through the unit test code for each reply that Bob should return, showing the tests for each reply.</p> <p>Each rule also had to ensure it did not create any false positives by being true for any other reply that Bob could make, especially the whatever reply.</p> Name Rule description question The phrase has a ? as the last alphanumeric character, not including whitespace shouting The phrase has uppercase alphabetic characters, but no lower case alphabetic characters shouting question A combination of question and shouting silence The phrase is empty or contains characters that are not alphanumeric whatever Any phrase that does not match any of the other rules"},{"location":"coding-challenges/exercism/bob/#design-approach","title":"Design approach","text":"<p>There are two main approaches to solving this challenge.  The first is to use the <code>clojure.string</code> functions to check or transform the phrase given to Bob.  The second approach is to use regular expressions with functions such as <code>re-seq</code>, <code>re-find</code> and <code>re-matches</code>.</p> <p>Start by defining the rules as an expression that returns either true or false, using some of the example strings from the unit tests.</p> <p>Use a <code>let</code> expression to bind a name to each rule, e.g. <code>shouting?</code>, <code>question?</code>, <code>silence?</code>.  Then these names can be used in a simple <code>cond</code> expression to return the appropriate phrase.  Regardless of if using <code>clojure.string</code> or regular expressions, the <code>cond</code> code should be similar</p> <p>Once you have tried this challenge for yourself, take a look at the design journal for the clojure.string approach and the regular expression approach.</p> <p>Bob - clojure.string approach Bob - regular expression approach</p>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/","title":"Bob solution - regex","text":"<p>Solution to Bob challenge using regular expressions and the <code>re-matches</code> function.</p> <p>Using <code>re-matchers</code>, if the string matches the pattern, then the string is returned. Otherwise <code>nil</code> is returned</p> <p>The regular expressions cheatsheet from Mozilla Developer Network was very helpful in understanding regular expressions</p>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#asking-bob-a-question","title":"Asking Bob a question?","text":"<p>The phrase passed to Bob is a question if the last alphanumeric character is a question mark. Using a simple regular expression we can check if the last character in the string a <code>?</code></p> <p><code>#\"\\?\"</code> is a literal regular expression pattern that will match a single <code>?</code> character</p> <p>So the regular expression pattern will match a single ? character</p> <pre><code>  (re-matches #\"\\?\" \"?\")\n</code></pre> <p>With other characters present though the pattern doesn't match.</p> <pre><code>  (re-matches #\"\\?\" \"Ready?\")\n</code></pre> <p>To match <code>?</code> with other characters,</p> <p><code>.</code> matches any single character except line terminators (new line, carriage return)</p> <pre><code>(re-matches #\".\\?\" \"R?\")\n</code></pre> <p><code>.*</code> matches any number of single characters one or more times,</p> <pre><code>(re-matches #\".*\\?\" \"?Ready\")\n</code></pre> <p><code>\\s</code> matches a single whitespace character and <code>\\s*</code> matches multiple whitespace characters</p> <pre><code>  (re-matches #\".*\\?$\" \"Okay if like my  spacebar  quite a bit?\")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit?\"\n</code></pre> <p><code>$</code> is a boundary assertion so the pattern only matches the ? at the end of a string and not in the middle.  However, this is not required as the <code>re-matches</code> uses groups and that manages the boundary assertion.</p> <p><code>re-matches</code> does not require the <code>$</code> as there is an implicit boundary</p> <pre><code>  (re-matches #\".*\\?\" \"Okay if like my ? spacebar  quite a bit\")\n</code></pre> <p>Match if there is a single space or space type character after the ?</p> <pre><code>  (re-matches #\".*\\?\\s\" \"Okay if like my  spacebar  quite a bit? \")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit? \"\n</code></pre> <p>Match if there are multiple space type characters after the ?</p> <pre><code>  (re-matches #\".*\\?\\s*\" \"Okay if like my  spacebar  quite a bit?   \")\n  ;; =&gt; \"Okay if like my  spacebar  quite a bit?   \"\n</code></pre> <p>Don't match if a question mark character is not at the end of the string</p> <pre><code>  (re-matches #\".*\\?\" \"Okay if like my ? spacebar  quite a bit\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#shouting-a-question-at-bob","title":"Shouting a question at Bob","text":"<p><code>[^a-z]</code> matches if there are no lower case alphabetic characters.  The <code>^</code> at the start of the pattern negated the pattern.</p> <p><code>*</code> any number of the proceeding pattern</p> <p><code>[A-Z]+</code> any number of upper case alphabetic characters</p> <p>When a phrase has all uppercase characters then we have a match</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"HELLO\")\n</code></pre> <p>If there are lower case characters, even if there are uppercase characters, the pattern does not match.</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"Hello\")\n</code></pre> <p>If the characters are all uppercase then the pattern matches, even if there are other non-alphabetic characters</p> <pre><code>  (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" \"ABC 1 2 3\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#silence-of-the-bob","title":"Silence of the Bob","text":"<p><code>\\s</code> matches any single whitespace character, including space, tab, form feed, line feed, and other Unicode spaces.</p> <pre><code>(re-matches #\"\\s*\" \"  \\t\\t\\t\")\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-regular-expression-approach/#solution-using-regular-expressions","title":"Solution using regular expressions","text":"<p>The <code>re-matches</code> expressions with regular expressions patterns can be put into a let expression.  The names are bound to the re-matches expressions which evaluated to either <code>true</code> or <code>false</code></p> <p>The names from the let are used with a <code>cond</code> function as conditions, returning the relevant reply from Bob.</p> <p>For the shouting question, the <code>and</code> is used to check if two names are both true.</p> <pre><code>(defn response-for\n  [phrase]\n  (let [;; A ? at the end of the phrase, not counting whitespace\n        question (re-matches #\".*\\?\\s*\" phrase)\n\n        ;; No lower case characters, at least one upper case character\n        yelling (re-matches #\"[^a-z]*[A-Z]+[^a-z]*\" phrase)\n\n        ;; The entire string is whitespace\n        silence (re-matches #\"\\s*\" phrase)]\n\n    (cond\n      silence                \"Fine. Be that way!\"\n      (and question yelling) \"Calm down, I know what I'm doing!\"\n      question               \"Sure.\"\n      yelling                \"Whoa, chill out!\"\n      :whatever              \"Whatever.\")))\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/","title":"Bob string approach","text":"<p>Solution to Bob challenge using <code>clojure.string</code> functions and Character class from Java.</p>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#asking-bob-a-question","title":"Asking Bob a question?","text":"<p>The phrase passed to Bob is a question if the last alphanumeric character is a question mark.</p> <p>Using a simple comparison we can check if the last character in the string a <code>?</code></p> <pre><code>(= \\? (last \"this is a question?\"))\n</code></pre> <p>However if there is whitespace after the question mark then the <code>last</code> character is a whitespace and so the expression returns false</p> <pre><code>  (= \\? (last \"this is still a question? \"))\n</code></pre> <p><code>clojure.string/trimr</code> will remove all the trailing whitespace from the right side of a string.  Once trimmed, then our initial comparison code will work again.</p> <pre><code>  (= \\? (last (clojure.string/trimr \"this is still a question? \")))\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#shouting-at-bob","title":"Shouting at Bob","text":"<p>Unfortunately the  clojure.string API does not have a function to check if a string is in capital letters.  There is an <code>upper-case</code> function, so a comparison can be made  with the original string and the string returned from <code>clojure.string/upper-case</code>.</p> <p>Convert the string to uppercase</p> <pre><code>(clojure.string/upper-case \"watch out!\")\n</code></pre> <p>compare the uppercase version of the string with the original, if they are equal, then the original string must have been in upper case</p> <pre><code>  (= \"WATCH OUT!\"\n     (clojure.string/upper-case \"WATCH OUT!\"))\n</code></pre> <pre><code>  (= \"watch out!\"\n     (clojure.string/upper-case \"watch out!\"))\n</code></pre> <p>There is a flaw in this approach thought, as it will give false positives for strings that should return the 'Whatever' response</p> <pre><code>  (= \"1, 2, 3\"\n     (clojure.string/upper-case \"1, 2, 3\"))\n</code></pre> <p>Refined rule to check that the phrase contains alphabetic characters, otherwise it is not shouting.</p> <p>The java.lang.Character class has a method called isLetter that determines if a character is a letter.</p> <p>The Classes and methods in <code>java.lang</code> are always available within a Clojure project, without the need for specifically importing the library.</p> <p><code>Character/isLetter</code> can be called as a function in Clojure, passing in a character type.</p> <pre><code>(Character/isLetter \\a)\n</code></pre> <p>To support all Unicode characters there is an isLetter method that takes an integer type.  As there could be any kind of characters in the phrase, we will use the int version.  This required conversing the character to an int first before calling <code>Character/isLetter</code></p> <pre><code>(Character/isLetter (int \\a))\n</code></pre> <p>the <code>some</code> function is used to iterate over all the characters in the phrase. As soon as a letter is found it returns true, so does not need to process the whole phrase unless no letter is found.</p> <pre><code>(some #(Character/isLetter (int %)) phrase)\n</code></pre>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#silence-of-the-bob","title":"Silence of the Bob","text":"<p><code>clojure.string/blank?</code> is a predicate function that returns true if a string is empty or contains only whitespace.  It also returns true for a <code>nil</code> value.</p>"},{"location":"coding-challenges/exercism/bob/bob-string-approach/#final-solution","title":"Final solution","text":"<p>Each of the rules is bound to a name that represents either a true or false value returned from each expression.</p> <p>The <code>cond</code> expression then evaluates the local names to see if they are true or false.  The first true value found returns the string associated with the name.</p> <p>For the shouting question, the <code>and</code> is used to check if two names are both true.</p> <pre><code>(defn response-for [phrase]\n  (let [phrase    (string/trimr phrase)\n        silence?  (string/blank? phrase)\n        question? (= \\? (last phrase))\n        letters?  (some #(Character/isLetter (int %)) phrase)\n        shouting? (and (= phrase (string/upper-case phrase))\n                       letters?)]\n    (cond\n      (and shouting? question?) \"Calm down, I know what I'm doing!\"\n      silence?                  \"Fine. Be that way!\"\n      shouting?                 \"Whoa, chill out!\"\n      question?                 \"Sure.\"\n      :else                     \"Whatever.\")))\n</code></pre> <p>The first let binding, <code>phrase</code> over-rides the name of the argument to the function.  This is not that common an approach as over-riding can lead to confusion.  However, in this relatively simple example it feels okay to do.  The over-ride is the first let binding and it is preparing the string for all the other let bindings to use.</p> <p>Over-riding names of functions from the Clojure standard library is not recommended as this does lead to much confusion.</p>"},{"location":"coding-challenges/palindrome/","title":"Project Palindrome","text":"<p>In this section we will create a simple Clojure project using Leiningen and build up a palindrome checker step by step.</p> <p>We will start with the simplest possible thing we can create and steadily add</p>"},{"location":"coding-challenges/palindrome/#what-is-a-palindrome","title":"What is a Palindrome","text":"<p>For this project it is assumed that a palindrome is a string of characters from the English alphabet and not any other language or an alphanumeric sequence.</p> <p>It is assumed that a palindrome is at least 3 characters long, meaning a single character cannot be a palindrome.  If a single character was a palindrome, then any valid sequence would contain at least as many palindromes as characters in that sequence.</p>"},{"location":"coding-challenges/palindrome/#challenge","title":"Challenge","text":"<p>Write an algorithm to find the 3 longest unique palindromes in a string. For the 3 longest palindromes, report the palindrome, start index and length in descending order of length. Any tests should be included with the submission.</p> <p>For example, the output for string, <code>\"sqrrqabccbatudefggfedvwhijkllkjihxymnnmzpop\"</code> should be:</p> <pre><code>Text: hijkllkjih, Index: 23, Length: 10\nText: defggfed, Index: 13, Length: 8\nText: abccba, Index: 5 Length: 6\n</code></pre> <ul> <li>Check for a palindrome</li> <li>Generate a series of palindromes</li> </ul>"},{"location":"coding-challenges/palindrome/simple-palindrome-test/","title":"Simple palindrome test","text":""},{"location":"continuous-integration/","title":"Continuous Integration","text":"<p>Topics to be covered in this section include:</p> <ul> <li> Continuous Integration services</li> <li> Circle CI</li> <li> GitHub Workflow</li> <li> GitLab CI</li> <li> Configure deployment pipelines</li> <li> Manage environment variables</li> <li> Security &amp; Secrets</li> <li> Deployment</li> <li> Amazon AWS</li> <li> Render.com</li> </ul> <p>CircleCI example in Practicalli Clojure Web Services</p> <p>Banking on Clojure is an example of Continuous Integration using CircleCI, with LambdaIsland/Kaocha as the test runner and Heroku as the deployment pipeline.</p>"},{"location":"continuous-integration/#12-factor-approach","title":"12 Factor approach","text":"<p>Following the 12 factor principles, the deployment is driven by source code to multiple environments.</p>"},{"location":"continuous-integration/#circleci-service","title":"CircleCI service","text":"<p>Use Yaml language to write CI workflows and tasks, using Docker images as a consistent run-time environment</p> <p>A commercial service with a generous free Cloud plan - (6,000 minutes), providing highly optomises container images to run tasks efficiently.  The CircleCI Clojure images contain Clojure CLI, Leiningen and Babashka pre-installed.</p> <p>CircleCI Orbs package up common configuration and tools, greatly simplifying the configuration and maintenance required.</p> <p>CircleCI Clojure language guide</p>"},{"location":"continuous-integration/#github-workflow","title":"GitHub Workflow","text":"<p>Use Yaml language to write CI workflows and tasks.</p> <p>A commercial service with a modest free plan (2,000 minutes) for open source projects.  GitHub Marketplace contains a wide range of Actions, including Clojure related actions, simplifying the configuration of CI.</p> <p>Setup Clojure provides Clojure CLI, Leinigen and boot tools for use within the CI workflow</p> <p>GitHub Actions overview</p>"},{"location":"continuous-integration/circle-ci/","title":"Circle CI continuous integration service","text":"<p>Circle CI is a service to build, test and deploy projects.  CircleCI uses docker images to run its workflow, either in the cloud or locally.</p> <p>Projects can be build, tests run, artifacts (uberjars) created and applications deployed to services such as AWS, Render.com, etc.</p> <p>Integration will be supported by Git version control, a continuous integration service (CircleCI, GitLabs, GitHub Actions) and a deployment platform (Heroku).</p>"},{"location":"continuous-integration/circle-ci/#getting-started","title":"Getting Started","text":"<p>Sign up using a GitHub or Bitbucket account and login to the CircleCI dashboard.</p> <p>Add Project in the CircleCI dashboard to configure a shared Git repository and run build pipelines using a <code>.circleci/config.yml</code> file in the root of the Clojure project.</p> <p>Every time changes are pushed to the shared code repository (GitHub, Bitbucket), CirceCI will run the pipeline for the project and show the results.</p>"},{"location":"continuous-integration/circle-ci/#clojure-images","title":"Clojure images","text":"<p>Clojure specific container images are available for several versions of Java and Clojure.  Pre-configured images are typically faster than installing software on top a more generic image.</p> <p><code>cimg/clojure:1.10</code> is the recommended image for Clojure projects. The image contains OpenJDK 17 and the latest version of Clojure CLI, Leiningen and Babashka</p> <p>Add the following under the <code>docker:</code> key in the <code>config.yml</code></p> <pre><code>- image: cimg/clojure:1.10\n</code></pre> <p>The CircleCI Clojure Language guide walks through the sections of the yaml configuration in detail.</p> Check Clojure version <p><code>clojure -Sdescribe</code> shows configuration information for the Clojure CLI tool as a hash-map, with the :version key associated with the exact install version.</p> <p><code>lein version</code> shows the current version of Leiningen install on your development environment.</p> <p><code>java -version</code> shows the current version of the Java installation.</p>"},{"location":"continuous-integration/circle-ci/#references","title":"References","text":"<p>CircleCI Clojure Language guide CircleCI Clojure image tags - json   CircleCI Clojure images  CircleCI dockerfiles repository</p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/","title":"Circle CI example project","text":"<p>The Circle CI language guide for Clojure provides an example project that is managed by the Leiningen build automation tool and based on the Luminus micro-framework template.</p> <p>The project runs on the Undertow web server (wrapped by immutant), using ring to manage web requests and responses, with compojure for server-side routing.  The application uses mount to manage the application lifecycle.</p> <p>Fork the CircleCI-Public/circleci-demo-clojure-luminus project on your GitHub or GitLab account or organisation.</p> <p>Go to the CircleCI dashboard and login.  Select the GitHub / GitLab organisation you want to work with, this will list the repositories in that organisation.</p> <p></p> <p>Find the project in the list of repositories for that organisation</p> <p></p> <p>Click on the \"Set Up Project\" button and select the Clojure configuration from the drop-down menu.</p> <p></p> <p>This template seems to be older than the sample configuration on the Clojure language page.  Copy the sample configuration and paste it into the editor.  Then press Add Config to automatically add it to your code repository.</p> <p>This will start a build and show the pipelines dashboard, with the project running the tasks defined in the configuration</p> <p></p> <p>Oh, it failed...</p> <p></p> <p>Clicking on the FAILED button shows details of that particular pipeline.  This opens the build report for the pipeline.</p> <p>The build report shows all the steps that have passed and the details of the step which has failed, in this case lein do test, uberjar</p> <p></p> <p>Edit the <code>.circleci/config.yml</code> file in your fork and change the images used to <code>openjdk-8-lein-2.9.3</code>.</p> <p>Then commit the change to the code in the code repository. Another build will run automatically.</p> <p></p> <p>The dashboard shows the second build of this pipeline, showing the new commit just pushed</p> <p></p> <p>Success.  Now development can continue knowing the configuration of the pipeline works.</p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/#hintfailing-on-java-11","title":"Hint::Failing on Java 11","text":"<p>The example project only seems to run on Java 8.  Running the project locally with either <code>lein run</code> or <code>lein test</code></p>"},{"location":"continuous-integration/circle-ci/circle-ci-sample-project/#hintcannot-edit-configuration-via-dashboard","title":"Hint::Cannot edit configuration via dashboard","text":"<p>Apart from the initial creation of the configuration, its not possible to edit the configuration via the dashboard.</p>"},{"location":"continuous-integration/circle-ci/detailed-config/","title":"Circle CI detailed configuration","text":""},{"location":"continuous-integration/circle-ci/detailed-config/#orbs","title":"Orbs","text":"<p>CircleCI Orbs are pre-packaged configurations for specific tasks, reducing the amount of configuration to maintain.</p> Orbs Description h-matsuo/github-release@0.1.3 GitHub release - package up releases ? Deploy to Heroku Kaocha test runner - unit and generative testing, junit-xml reports and test coverage"},{"location":"continuous-integration/circle-ci/detailed-config/#executors","title":"Executors","text":"<p>Define an executor for the environment used to run the CircleCI jobs.</p> Executor environment Description machine Linux virtual machine docker <p>Configuration for a Clojure CLI project</p> <pre><code>---\nversion: 2.1\n\norbs:\n  github-release: h-matsuo/github-release@0.1.3\n\nexecutors:\n  tools-deps-executor:\n    docker:\n      - image: circleci/clojure:openjdk-11-tools-deps-1.10.1.697\n    working_directory: ~/repo\n    environment:\n      JVM_OPTS: -Xmx3200m\n\ncommands:\n  setup:\n    steps:\n      - checkout\n      - restore_cache:\n          keys:\n            - v1-dependencies-{{ checksum \"deps.edn\" }}\n            - v1-dependencies-\n      - save_cache:\n          paths:\n            - ~/.m2\n          key: v1-dependencies-{{ checksum \"deps.edn\" }}\n\n  acceptance-tests:\n    steps:\n      - run:\n          name: check coverage\n          command: clojure -M:test:coverage\n\n  deploy-version:\n    steps:\n      - run:\n          name: Update pom.xml\n          command: clojure -Spom\n      - run:\n          name: Build\n          command: clojure -M:jar\n      - run:\n          name: Deploy\n          command: clojure -M:deploy\n\n  store-artifact:\n    steps:\n      - run:\n          name: Create jar\n          command: clojure -M:jar\n      - run:\n          name: Zip up jar file\n          command: zip --junk-paths github-api-lib github-api-lib.jar\n      - run:\n          name: install mvn\n          command: |\n            sudo apt-get update\n            sudo apt-get -y install maven\n      - run:\n          name: extract version from pom\n          command: |\n            mvn help:evaluate -Dexpression=project.version -q -DforceStdout &gt; current_version\n      - persist_to_workspace:\n          root: ~/repo\n          paths:\n            - github-api-lib.zip\n            - current_version\n\n  create-release:\n    steps:\n      - attach_workspace:\n          at: ~/repo\n      - github-release/create:\n          tag: \"v$(cat ~/repo/current_version)\"\n          title: \"Version v$(cat ~/repo/current_version)\"\n          description: \"Github-related API calls.\"\n          file-path: ~/repo/github-api-lib.zip\n\n\n\njobs:\n  test:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - acceptance-tests\n  deploy:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - acceptance-tests\n      - deploy-version\n  artifact:\n    executor: tools-deps-executor\n    steps:\n      - setup\n      - store-artifact\n  release:\n    executor: github-release/default\n    steps:\n      - setup\n      - create-release\n\n\nworkflows:\n  build-test-release:\n    jobs:\n      - test\n      - deploy:\n          context: clojars\n          requires:\n            - test\n          filters:\n            branches:\n              only: main\n      - artifact:\n          requires:\n            - test\n          filters:\n            branches:\n              only: main\n      - release:\n          context: github\n          requires:\n            - test\n            - deploy\n            - artifact\n          filters:\n            branches:\n              only: main\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/","title":"Random Clojure Function","text":"<p>A Clojure command line application that shows a random function from the namespaces available in the Clojure Standard library, or a specific namespace from that library.</p> <p>Random Clojure Function repository</p> <p>This guide shows how to develop this project alongside CircleCI as the continuous integration service.</p> <ol> <li>Create a new project - using the Random Clojure Function guide</li> <li>Create a repository on GitHub</li> <li>Commit the project early and push changes to GitHub</li> <li>Add a .circleci/config.yml file and push to GitHub, choosing the relevant image</li> <li>Login to CircleCI dashboard and add project, choosing manual configuration</li> <li>Continue developing the random clojure function project, including tests</li> <li>After each push to GitHub, check the build status</li> <li>Add a CircleCI badge to the project readme</li> </ol> <p> </p> <p>Video uses an older command to create projects</p> <p><code>:project/create</code> alias from  Practicalli Clojure CLI Config creates a new project</p> <p>Arguments are key value pairs and can specify the <code>:template</code>, project <code>:name</code> and outpug directory <code>:output-dir</code>. <pre><code>clojure -T:project/new :template app :name practicalli/playground`\n</code></pre></p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#create-a-new-project","title":"Create a new project","text":"<p>Start following the guide to create the random clojure function project, using a deps.edn for the Clojure project configuration</p> <pre><code>clojure -T:project/new :template app :name practicalli/random-clojure-function\n</code></pre> <p>Version control the Clojure project using Git (or magit in Spacemacs)</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#add-a-test-run-alias","title":"Add a test run alias","text":"<p>Edit the <code>deps.edn</code> file in the root of the project and add a <code>:test/run</code> alias, to run the kaocha test runner which will stop if a failing test is detected.  Stopping on a failed test saves running the full test suite and make the CI workflow more effective.</p> Project deps.edn<pre><code>:test/run\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.60.977\"}}\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:randomize? false\n             :fail-fast? true}}\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#create-a-remote-repository","title":"Create a remote repository","text":"<p>Add the remote repository URL to the local Git repository.</p> <pre><code>git remote add practicalli git@github.com:practicalli/random-clojure-function.git\n</code></pre>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#add-circleci-configuration","title":"Add CircleCI configuration","text":"<p>Adding CircleCI early in the project development cycle ensures testing from the saved source code is successful and testing is consistently repeatable.</p> <p>Create a new file called <code>.circleci/config.yaml</code> in the root of the project.</p> <p>Edit the file and add the following configuration.</p> <p>Circe CI configuration for Clojure project</p> <p><code>``yaml title=\".circleci/config.yaml\" version: 2.1 jobs:                                               # basic units of work in a run   build:                                            # runs without Workflows must have a</code>build<code>job as entry point     working_directory: ~/random-clojure-function    # directory where steps will run     docker:                                         # run the steps with Docker       - image:  cimg/clojure:1.10                   # image is primary container where</code>steps<code>are run     environment:                                    # environment variables for primary container       JVM_OPTS: -Xmx3200m                           # limit maximum JVM heap size to prevent out of memory errors     steps:                                          # commands that comprise the</code>build` job       - checkout                                    # check out source code to working directory       - restore_cache:                              # restores cache if checksum unchanged from last run           key: random-clojure-function-{{ checksum \"deps.edn\" }}       - run: clojure -P       - save_cache:                                 # generate / update cache in the .m2 directory using a key template           paths:             - ~/.m2             - ~/.gitlibs           key: random-clojure-function-{{ checksum \"deps.edn\" }}       - run: clojure -X:test/run</p> <p>```</p> <p><code>run: clojure -P</code> step downloads dependencies for the project, including the <code>:extra-deps</code> if aliases are also included.</p> <p><code>run: clojure -X:test/run</code> adds the test directory to the class path and runs the Kaocha runner defined in the alias.</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#connect-circle-ci-to-the-project","title":"Connect Circle CI to the project","text":"<p>Commit and push the <code>.circleci/config.yml</code> file to the GitHub repository.</p> <p>Open the CircleCI dashboard and select Add Project.  If your GitHub account has multiple organizations, choose the appropriate organization first.</p> <p>Search the repository list for the GitHub repository and select ,,,</p> <p></p> <p>Select the Manual configuration as a <code>.circleci/config.yml</code> file has already been added to the Git repository.</p> <p></p> <p>Press Start Building button to confirm that a <code>config.yml</code> file has already been added and the build should start.</p> <p></p> <p>Now the first build runs with the <code>config.yml</code> file.</p> <p></p> <p>Its failed.  Okay lets investigate...</p> <p></p> <p>Thats okay, we have failing tests locally, so we know that the CircleCI build is working the same as on our local development environment.</p> <p>The continuous integration is now working and tests are automatically run as soon as you push changes to the remote repository.</p> <p>So the development of the project can continue with greater confidence</p>"},{"location":"continuous-integration/circle-ci/random-clojure-function/#adding-a-build-status-badge","title":"Adding a Build Status badge","text":"<p>Generating a status badge documentation describes how to add a build status badge for your project, usually at the top of the README.md file in the project</p> <pre><code>[![CircleCI](https://circleci.com/gh/circleci/circleci-docs.svg?style=svg)](https://circleci.com/gh/practicalli/random-clojure-function)\n</code></pre> <p>Add this markdown to the top of the README.md file, underneath the title.  Then commit and push the change to the GitHub repository.</p> <p>NOTE: you might want to fix the unit tests first :)</p>"},{"location":"continuous-integration/circle-ci/status-monitor/","title":"Status Monitor Circle CI Continuous Integration","text":"<p>practicalli/webapp-status-monitor is a Leiningen project create in October 2018.</p> <p>The project uses ring and compojure as the basis of a web application.</p> <p>Configured with a project.clj file.</p> <pre><code>(defproject status-monitor \"0.1.0-SNAPSHOT\"\n  :description \"A server side website dashboard to collate monitoring information\"\n  :url \"https://github.com/jr0cket/status-monitor\"\n  :min-lein-version \"2.0.0\"\n  :dependencies [[org.clojure/clojure \"1.9.0\"]\n                 [compojure \"1.6.1\"]\n                 [ring/ring-defaults \"0.3.2\"]\n                 [hiccup \"1.0.5\"]]\n  :plugins [[lein-ring \"0.12.4\"]\n            [lein-eftest \"0.5.3\"]]\n  :ring {:handler status-monitor.handler/app}\n  :profiles\n  {:dev {:dependencies [[javax.servlet/servlet-api \"2.5\"]\n                        [ring/ring-mock \"0.3.2\"]]}})\n</code></pre>"},{"location":"continuous-integration/circle-ci/status-monitor/#circleci-configuration","title":"CircleCI Configuration","text":"<p>This configuration uses the CircleCI specific docker image with Java 17 and the latest version of Leiningen.</p> <p>The configuration defines that the code will be check out, Leiningen will download the dependencies and then run unit tests.</p> <pre><code>version: 2\njobs:\n  build:\n    docker:\n      - image: cimg/clojure:1.10\n\n    working_directory: ~/repo\n\n    environment:\n      LEIN_ROOT: \"true\"\n      # Customize the JVM maximum heap limit\n      JVM_OPTS: -Xmx3200m\n\n    steps:\n      - checkout\n\n      # Download and cache dependencies\n      - restore_cache:\n          keys:\n          - v1-dependencies-{{ checksum \"project.clj\" }}\n          # fallback to using the latest cache if no exact match is found\n          - v1-dependencies-\n\n      - run: lein deps\n\n      - save_cache:\n          paths:\n            - ~/.m2\n          key: v1-dependencies-{{ checksum \"project.clj\" }}\n\n      # run tests!\n      - run: lein test\n</code></pre>"},{"location":"continuous-integration/circle-ci/status-monitor/#caching-dependencies","title":"Caching dependencies","text":"<p>CircleCI create a cache of downloaded dependencies, to help speed up the running of the project.</p> <p>The config.yml defines the path where the dependencies are saved.  A unique key is used to identify the dependencies cache.</p> <p></p>"},{"location":"continuous-integration/github-workflow/","title":"GitHub Workflows","text":"<p>Automate tasks, such as running unit tests or lint code, whenever code is committed to a  GitHub repository.</p> <p>GitHub Actions can run one or more tasks after specific events, such as commits, raising issues or pull requests.</p> <p>An event triggers a configured workflow which contains one or more jobs. A job contains a one or more steps which defines actions to run.</p> <p>Practicalli GitHub Workflow Examples Practicalli recommended GitHub Actions</p> <p>Introduction to GitHub Actions Understanding the workflow file</p>"},{"location":"continuous-integration/github-workflow/#anatomy-of-a-workflow","title":"Anatomy of a workflow","text":"Term Description Event Triggers a workflow, e.g. Create pull request, push commit, etc. Workflow Top level configuration containing one or more jobs, triggered by a specific event Job Set of steps executed in the same runner, multiple jobs execute in parallel within their own instance of a runner Step Individual task that runs commands (actions), sharing data with other steps Action Standalone commands defined within a step, custom commands or GitHub community Runner A GitHub Actions server, listening for available jobs"},{"location":"continuous-integration/github-workflow/#example-github-action","title":"Example GitHub Action","text":"<p><code>.github/workflows/workflow-name.yaml</code> is a file that contains the workflow definition.</p> <p>Setup Java adds an OpenJDK distribution, i.e. Eclipse Temurin, at a specified version (Java 17 recommended).</p> <p>Setup Clojure provides Clojure via Clojure CLI, Leiningen or Boot.  Clojure CLI is recommended.</p> <p>Cache is used to cache Clojure and Java libraries</p> <ul> <li>The example workflow runs on Ubuntu.</li> <li>The project code is checked out from the Git repository.</li> <li>Java and Clojure run-times are added to the environment</li> <li>Unit tests are run using the <code>:test/run</code> alias (this alias should run Kaocha or similar test runner)</li> <li>Source code format and idioms are checked with cljstyle and clj-kondo</li> <li>The Clojure project is packaged into an Uberjar for deployment</li> </ul> <p>Example GitHub workflow for Clojure CLI project</p> <pre><code>name: Test and Package project\non:\n  pull_request:\n  push:\n    branches:\n      - main\njobs:\n  clojure:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Cache Clojure Dependencies\n        uses: actions/cache@v3\n        with:\n          path:\n            - ~/.m2\n            - ~/.gitlibs\n          key: cache-${{ hashFiles('**/deps.edn') }}\n          restore-keys: clojure-deps-\n\n      - name: Prepare java\n        uses: actions/setup-java@v3\n        with:\n          distribution: 'temurin'\n          java-version: '17'\n\n      - name: Install clojure tools\n        uses: DeLaGuardo/setup-clojure@9.5\n        with:\n          cli: 1.11.1.1165    # Clojure CLI based on tools.deps\n          cljstyle: 0.15.0 # cljstyle\n          clj-kondo: 2022.10.05 # Clj-kondo\n\n      - name: Run Unit tests\n        run: clojure -X:test/run\n\n      - name: \"Lint with clj-kondo\"\n        run: clj-kondo --lint deps.edn src resources test --config .clj-kondo/config-ci.edn\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - name: Package Clojure project\n        run: clojure -X:project/uberjar\n</code></pre>"},{"location":"continuous-integration/github-workflow/#references","title":"References","text":"<ul> <li>Practicalli Blog - publish blog workflow - build publish a Cryogen project with Clojure CLI and publish the generated website with GitHub pages (also a Staging workflow that runs on pull requests)</li> <li>Practicalli Landing Page GitHub workflow - build a ClojureScript &amp; Figwheel project with Clojure CLI and publish the generated site to GitHub pages</li> <li>Practicalli Clojure CLI config - lint with clj-kondo workflow - lint the <code>deps.edn</code> file with clj-kondo</li> </ul>"},{"location":"control-flow/cond/","title":"cond","text":""},{"location":"control-flow/if/","title":"if","text":""},{"location":"control-flow/when/","title":"when","text":""},{"location":"core.async/","title":"Introducing core.async","text":"<p>The <code>core.async</code> library provides a way to do concurrent programming using channels (eg. queues).</p> <p>It minimises the need to use complex concurrent constructs and worry less about thread management.</p> <p><code>core.async</code> is written in Clojure and can be used with both Clojure and ClojureScript.</p> <ul> <li>core.async getting started</li> <li>Introduction to asynchronous programming</li> <li>ClojureScript core.async and todos - Bruce Haurman</li> <li>core.async 101</li> <li>Mastering concurrent processes</li> <li>LispCast Clojure core.async: Channels - first lesson only.</li> <li>core.async introduction in ClojureScrpt unravelled</li> <li>core.async: Concurrency without Callbacks - Stuart Halloway</li> <li>David Nolan - core.async for asynchronous programming</li> <li>Timothy Baldridge - Core.Async</li> <li>core.async in Use - Timothy Baldridge</li> <li>Timothy Baldridge - core.async - pipelines - free video</li> <li>Timothy Baldridge - core.async - garbage collected go blocks - free video</li> </ul>"},{"location":"core.async/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/#hint-coreasync-resources","title":"Hint:: core.async resources","text":""},{"location":"core.async/#hintcommunicating-sequential-processes","title":"Hint::Communicating Sequential Processes","text":"<p>Communicating Sequential Processes (CSP) is a formalism for describing concurrent systems pioneered by C. A. R. Hoare in 1978. It is a concurrency model based on message passing and synchronization through channels</p>"},{"location":"core.async/#coreasync-on-clojurescript","title":"core.async on ClojureScript","text":"<p>core.async is very widely used within ClojureScript applications and many libraries are built on top of it.</p> <p>It\u2019s a good example of the syntactic abstractions that can be achieved by transforming code with ClojureScript macros.</p> <p>JavaScript is single-threaded so you do not get the benefit of safe communication between threads, as there is only one.</p>"},{"location":"core.async/#concepts","title":"Concepts","text":""},{"location":"core.async/#channels","title":"Channels","text":"<p>A channel is a queue with one or more publishers and one or more consumers.  Producers put data onto the queue, consumers take data from the queue.</p> <p>As data in Clojure is immutable, channels provide a safe way to communicate between threads.</p>"},{"location":"core.async/#chanel-size","title":"Chanel size","text":"<p>Channels do not include a buffer by default,  they use a producer (<code>put!</code>) and consumer (<code>take!</code>) to transfer a value through the channel.  A maximum of 1024 <code>put!</code> functions can be queued onto a single channel.</p> <p>Specify a channel using <code>(chan)</code> or a channel with a fixed buffer using <code>(chan 12)</code>.</p>"},{"location":"core.async/#processes","title":"Processes","text":"<p>Processes are independently running pieces of code that use channels for communication and coordination.</p> <p>Calling <code>put!</code> and <code>take!</code> inside a process will stop that process until the operation completes.</p> <p>Processes are launched using the go macro and puts and takes use the &lt;! and &gt;! placeholders. The go macro rewrites your code to use callbacks but inside go everything looks like synchronous code, which makes understanding it straightforward:</p> <p>In ClojureScript, stopping a process doesn\u2019t block the single-threaded JavaScript environment, instead, the process will be resumed at a later time when it is no longer blocked.</p>"},{"location":"core.async/#important-functions","title":"Important functions","text":""},{"location":"core.async/#chan","title":"<code>chan</code>","text":"<p>The <code>chan</code> function creates a new channel.</p> <p>You can give a name to a channel using the <code>def</code> function, eg. <code>(def my-channel (chan))</code></p> <p>A single channel can take a maximum of 1024 put requests.  Once it has reached the maximum, then it is considered full.</p> <p>A buffer of a fixed size can be specified when defining a new channel: <code>(def channel-with-fixed-buffer (chan 12))</code>.  This buffer increases the number of puts that can be sent to the channel.  A dropping or sliding buffer can be used to discard messages added when the buffer is full.</p> <p>A channel can also include a transducer, to manipulate the value on the channel eg. adding a timestamp <code>(chan 32 (map (Date. now)))</code> eg. filtering messages <code>(chan 12 (map even?))</code></p> <p>Channels can be explicitly closed using <code>(close channel-name)</code> or by adding a timeout that closes the channel after the specified number of milliseconds <code>(timeout 6000)</code>.</p>"},{"location":"core.async/#put","title":"<code>put!</code>","text":"<p>The <code>put!</code> function puts a value (message) on the channel.</p> <p>You can put messages on the channel even if nothing is listening (no waiting <code>take!</code> functions).</p> <p>Evaluating <code>put!</code> will always add a message on to the channel as long as the channel is open and not full.</p>"},{"location":"core.async/#take","title":"<code>take!</code>","text":"<p>The <code>take!</code> function will take a single message from the queue.</p> <p>If there are no messages on the queue when you evaluate <code>take!</code>, then the function will wait to execute as soon as something is put on the channel</p> <p>The <code>take!</code> function needs an argument that is the channel and a function that will receive any message taken from a channel.</p>"},{"location":"core.async/#time","title":"<code>time</code>","text":"<p>This is a macro that executes an expression and prints the time it takes</p> <p>Criterium is an excellent library for performance testing your code</p>"},{"location":"core.async/#go","title":"<code>go</code>","text":"<p>Referred to as a go block, the <code>go</code> function creates a lightweight process, not bound to threads.  Thousands of go blocks can be created efficiently and they can all have their own channel.</p>"},{"location":"core.async/#blocking-and-non-blocking","title":"blocking and non-blocking","text":"<p>core.async offers two ways to write to and read from channels: blocking and non-blocking. A blocking write blocks the thread until the channel has space to be written to (the buffer size of a channel is configurable), a blocking read blocks a thread until a value becomes available on the queue to be read.</p> <p>More interesting, and the only type supported in ClojureScript, are asynchronous channel reads and writes to channels, which are only allowed in \"go blocks\". Go blocks are written in a synchronous style, and internally converted to a state machine that executes them asynchronously.</p> <p>Consider the following core.async-based code:</p> <pre><code>(let [ch (chan)]\n  (go (while true\n        (let [v (&lt;! ch)]\n          (println \"Read: \" v))))\n  (go (&gt;! ch \"hi\")\n      (&lt;! (timeout 5000))\n      (&gt;! ch \"there\")))\n</code></pre> <p>In this example, let introduces a new local variable ch, which is a new channel. Within the let's scope two go blocks are defined, the first is an eternal loop that reads (&lt;!) a new value from channel ch into variable v. It then prints \"Read: \" followed by the read value to the standard out. The second go block writes (&gt;!) two values to channel ch: \"hi\", it then waits 5 seconds and then writes \"there\" to the channel. Waiting for 5 seconds is implemented by reading from a timeout channel, which is a channel that closes itself (returns nil) after a set timeout. When running this code in the Clojure REPL (for instance), it will return instantly. It will then print \"Read: hi\", and 5 seconds later it will print \"Read: there\".</p>"},{"location":"core.async/#hint","title":"Hint::","text":"<p>In JavaScript you cannot do blocking loops like this: the browser will freeze up for 5 seconds. The \"magic\" of core.async is that internally it converts the body of each go block into a state machine and turns the synchronous-looking channel reads and writes into asynchronous calls.</p>"},{"location":"core.async/bike-assembly-line/","title":"core.async scenario: Bike assembly line","text":"<p>In this example we are going to use a bicycle assembly line as the process we want to make concurrent.  The tasks involved in making our bicycle are:</p> <ul> <li>Making the frame</li> <li>Painting the wheels</li> <li>Making the rims</li> <li>Making the wheels (adding hub and spokes to wheels - different hub for front and rear wheels)</li> <li>Making the handlebars</li> <li>Fitting tyres to the rims (solid rims, so no tubes)</li> <li>Attaching the handlebars to the frame</li> <li>Attaching wheels to the frame</li> <li>Attaching crank to frame</li> <li>Attaching peddles to the crank</li> <li>Connecting control system wires (gears, breaks)</li> </ul>"},{"location":"core.async/bike-assembly-line/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/bike-assembly-line/#current-build-process","title":"Current build process","text":"<p>At the moment, each person creates one bicycle all by themselves.  This means they need all sorts of different tools and are switching tasks all the way through assembling the bike.</p> <p>We want to move to a more parallel approach, so as we automate this process we will evaluate what actions can be done in parallel and which must be done sequentially (i.e. painting the frame must come after making the frame).</p>"},{"location":"core.async/clacks-messages/","title":"Clacks Messenger with core.async","text":"<p>In a previous exercise we built a simple encoder/decoder to send messages via the Clacks message service (as designed by Sir Terry Pratchett, RIP).</p> <p>Now we will use core.async to create a processing queue between each Clack towers, so we can then model, monitor and visualise a Clacks messenger system with multiple Clacks towers.  For additional fun we will enable new Clacks towers to come on line and connect to the existing system.</p>"},{"location":"core.async/clacks-messages/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"core.async/toy-car-assembly-line/","title":"core.async example - toy car assembly line","text":""},{"location":"core.async/toy-car-assembly-line/#noteget-the-example-project-and-open-it-in-a-clojure-repl","title":"Note::Get the example project and open it in a Clojure REPL","text":"<p>Clone or download the Lispcast: Clojure core-async Factory example</p> <p>Open that project in your Clojure editor or run <code>lein repl</code> in the top level directory of the project.</p>"},{"location":"core.async/toy-car-assembly-line/#the-toy-car-factory","title":"The toy car factory","text":"<p>The toy car factory assembles car parts before distributing them.  How can we make this process faster and more scalable?</p>"},{"location":"core.async/toy-car-assembly-line/#the-current-process","title":"The current process","text":"<p>One worker picks out random parts of a car from the parts box until all the parts are collected to assemble the car.</p>"},{"location":"core.async/toy-car-assembly-line/#the-time-macro","title":"The <code>time</code> macro","text":"<p>We will use the time macro to see how long parts of our code takes to run and help find parts to optimise.</p> <p>A simple example would be:</p> <pre><code>(time\n  (map inc (range 0 10000)))\n</code></pre>"},{"location":"core.async/toy-car-assembly-line/#timing-assembly-functions","title":"Timing assembly functions","text":"<p>Investigate the time it takes to carry out the different assembly line tasks</p> <pre><code>(time (take-part))\n\n(time (attach-wheel :body :wheel))\n\n(time (box-up :body))\n\n(time (put-in-truck :body))\n</code></pre> <p>And to total time it takes to get a a whole car through the assembly line</p> <pre><code>(time (build-car))\n</code></pre> <p>The total time can be longer than the sum of the tasks, as the <code>take-part</code> function does not always give the required part needed.</p>"},{"location":"core.async/toy-car-assembly-line/#hiring-more-workers","title":"Hiring more workers","text":"<p>Adding 10 more workers is equivalent to adding 10 processes that run the assembly tasks.</p> <p>Lets use a go block for a worker</p> <pre><code>(do\n  (go\n    (dotimes [number 10]\n      (println \"First go block processing:\" number)\n      (Thread/sleep 1200)))\n  (go\n    (dotimes [number 10]\n      (println \"Second go block processing:\" number)\n      (Thread/sleep 1200))))\n</code></pre> <p>These are two separate go blocks, so their is no co-ordination between the two.  You can see the println statement from each go block intertwined.</p>"},{"location":"data-inspector/","title":"Clojure Data Browsers","text":"<p>Clojure has a strong focus on using the built in data structures (list, vector, hash-map, set) to represent information in the system.  Tools to inspect data and browse through nested or large data sets is invaluable in understanding what the system is doing.</p> <p>There are many <code>clojure.core</code> functions that can be used to explore data structures and transform them to produce specific views on data.</p> <p><code>tap&gt;</code> and <code>datafy</code> are recent additions to Clojure that provide a more elegant way of exploring data than the classic <code>println</code> statement.</p> <p>New tools are being created to capture and visualize results from evaluated expressions (REBL, Reveal) as well as tools to specifically visualize <code>tap&gt;</code> expressions (Reveal, Portal).</p>"},{"location":"data-inspector/#common-approaches","title":"Common approaches","text":"<ul> <li>Editor data browsers - e.g. cider-inspect</li> <li>Portal - tool to navigate and visualise data via <code>tap&gt;</code></li> <li>Clojure inspector - built-in Java Swing based inspector</li> <li>Reveal repl with data browser, also a <code>tap&gt;</code> source (semi-commercial project)</li> </ul>"},{"location":"data-inspector/clojure-inspector/","title":"Clojure Inspector","text":"<p>A visual browser for Clojure data using the Java UI libraries.</p> <p>Require the <code>clojure.inspector</code> namespace in the REPL or project namespace definitions to use the functions</p> ReplProject <pre><code>(require '[clojure.inspector :as inspector])\n</code></pre> <pre><code>(ns practicalli.application\n  (:require [clojure.inspector :as inspector]))\n</code></pre> <ul> <li><code>inspect</code> for flat data structures</li> <li><code>inspect-tree</code> for deeply nested / hierarchically data</li> <li><code>inspect-table</code> a sequence of data structures with the same shape</li> </ul>"},{"location":"data-inspector/clojure-inspector/#inspect","title":"<code>inspect</code>","text":"<p>View flat structures especially with non-trivial size data sets.</p> <p>This example generated 10,000 random numbers.  The Clojure inspector shows the values along with their index in the collection.</p> <pre><code>(inspector/inspect\n  (repeatedly 10000 #(rand-int 101)))\n</code></pre> <p></p>"},{"location":"data-inspector/clojure-inspector/#inspect-tree","title":"<code>inspect-tree</code>","text":"<pre><code>(inspect\n  {:star-wars\n    {:characters\n      {:jedi [\"obiwan kenobi\" \"Yoda\" \"Master Wendoo\"]\n       :sith [\"Palpatine\" \"Count Dukoo\"]}}})\n</code></pre>"},{"location":"data-inspector/clojure-inspector/#inspect-table","title":"<code>inspect-table</code>","text":"<p>Inspect a sequence of data structures that share the same form, often found in data sets for machine learning and wider data science, eg. daily weather records.</p> <p>This example generates mock data for a 20 day period for one or more locations.  Each day contains the day, location and cumulative number of cases reported.</p> <pre><code>(defn mock-data-set\n  \"Generates a set of mock data for each name\n  Arguments: names as strings, names used in keys\n  Returns: Sequence of maps, each representing confirmed cases\"\n  [&amp; locations]\n  (for [location locations\n        day      (range 20)]\n    {:day      day\n     :location location\n     :cases    (+ (Math/pow (* day (count location)) 0.8)\n                  (rand-int (count location)))}))\n\n(inspector/inspect-table\n  (mock-data-set \"England\" \"Scotland\" \"Wales\" \"Northern Ireland\"))\n</code></pre> <p></p>"},{"location":"data-inspector/portal/","title":"Portal - navigate your data","text":"<p>Portal inspector is a tool for exploration of Clojure data using a browser window to visualise and inspect Clojure, JSON, Transit, Logs, Yaml, etc.</p> <p>Registered Portal as a tap source and wrap code with <code>(tap&gt; ,,,)</code> to see the results in Portal, providing a more advanced approach to debuging than println.</p> <p>Send all evaluation results to Portal for a complete history using the portal-wrap nREPL middleware</p> <p>Add a custom Mulog publisher to send all logs to Portal to help with debugging.</p> <p>Open Portal from the REPL or configure Portal to open on REPL startup.</p> <p>Practicalli Project Templates</p> <p>Clojure projects created with Practicalli Project Templates include Portal configuration to recieve all evaluation results and Mulog event logs.</p> <p>A custom <code>dev/user.clj</code> file loads <code>dev/portal.clj</code> and <code>dev/mulog-events.clj</code> configurations on REPL startup, when the <code>dev</code> directory is included on the path.</p> <p>Use the <code>:repl/reloaded</code> for a complete REPL reloaded workflow and tooling on REPL startup</p> <p></p> Clojure 1.10 onward required tap sources and tap&gt; <p>tap is a shared, globally accessible system for distributing values (log, debug, function results) to registered tap sources.</p> <p><code>add-tap</code> to register a source and receive all values sent. <code>remove-tap</code> to remove a source.</p> <p><code>tap&gt;</code> form sends its contents to all registered taps. If no taps are registered, the values sent by tap&gt; are discarded.</p> <p><code>(deref (deref #'clojure.core/tapset))</code> will show the tap sources. <code>tapset</code> is a Clojure set defined as private var and not meant to be accessed directly.</p> <p>Online Portal demo</p>"},{"location":"data-inspector/portal/#add-portal","title":"Add Portal","text":"<p>Clojure CLI user configuration aliases enable Portal to be used with any Clojure or ClojureScript project.</p>  Practicalli Clojure CLI ConfigAlias Definition <p> Practicalli Clojure CLI Config contains several aliases that support Portal, either to start a REPL process that can send all Clojure evaluated code to Portal or simply adding Portal as a library for manual use.</p> <p>Run a REPL with portal and <code>portal.nrepl/wrap-portal</code> to send every REPL evaluation to Portal over an nREPL connection</p> <ul> <li><code>:repl/reloaded</code> - starts a rich terminal UI REPL with Portal nREPL middleware, including REPL Reloaded tools</li> <li><code>:repl/inspect</code> - starts a basic REPL with Portal nREPL middleware.</li> </ul> <p>Or include the portal library in <code>clojure</code> commands or when starting a REPL via an editor</p> <ul> <li><code>dev/reloaded</code> - Portal, including REPL Reloaded tools</li> <li><code>inspect/portal-cli</code> - Clojure CLI (simplest approach)</li> <li><code>inspect/portal-web</code> - Web ClojureScript REPL</li> <li><code>inspect/portal-node</code> - node ClojureScript REPL</li> </ul> <p>Create portal aliases to include the portal libraries for the Clojure, ClojureScript Web browser and ClojureScript Node server libraries</p> <p>Portal aliases in Clojure CLI user configuration</p> <pre><code>:inspect/portal-cli\n{:extra-deps {djblue/portal {:mvn/version \"0.34.2\"}\n              clj-commons/clj-yaml         {:mvn/version \"0.7.0\"}}}\n\n:inspect/portal-web\n{:extra-deps {djblue/portal             {:mvn/version \"0.34.2\"}\n              org.clojure/clojurescript {:mvn/version \"1.10.844\"}}\n :main-opts  [\"-m\" \"cljs.main\"]}\n\n:inspect/portal-node\n{:extra-deps {djblue/portal             {:mvn/version \"0.34.2\"}\n              org.clojure/clojurescript {:mvn/version \"1.10.844\"}}\n :main-opts  [\"-m\" \"cljs.main\" \"-re\" \"node\"]}\n\n:repl/inspect\n{:extra-deps\n {cider/cider-nrepl {:mvn/version \"0.28.5\"}\n  djblue/portal     {:mvn/version \"0.33.0\"}\n  clj-commons/clj-yaml         {:mvn/version \"0.7.0\"}}\n :main-opts [\"-m\" \"nrepl.cmdline\"\n             \"--middleware\"\n             \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"]}\n</code></pre> <p> Practicalli Clojure CLI Config contains several aliases that support Portal.</p> YAML support for Portal - Clojure only <p> clj-commons/clj-yaml adds YAML support to Portal for Clojure on the JVM</p> <p>REPL Reloaded Aliases</p> <p> REPL Reloaded section includes the <code>:repl/reloaded</code> and <code>:dev/reloaded</code> ailas definitions</p>"},{"location":"data-inspector/portal/#start-repl-with-portal","title":"Start REPL with Portal","text":"<p>Run a REPL in a terminal and include the Portal library, using the Clojure CLI tools</p> REPL StarupEmacs Project configurationEmacs variable <p>Start a REPL with namespace reloading, hotload libraries and portal data inspector</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Or start the REPL with only portal</p> <pre><code>clojure -M:inspect/portal:repl/rebel\n</code></pre> <p>Add <code>cider-clojure-cli-aliases</code> to a <code>.dir-locals.el</code> in the root of the Clojure project with an alias used to add portal</p> <p>.dir-locals.el</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":dev/reloaded\"))))\n</code></pre> <p>Or include an alias with only portal data inspector</p> <p>.dir-locals.el</p> <pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":inspect/portal-cli\"))))\n</code></pre> <p>Set <code>cider-clojure-cli-aliases</code> to the alias used to add portal, e.g. <code>inspect/portal</code></p> <p>Example</p> <pre><code>(setq cider-clojure-cli-aliases \":inspect/portal\")\n</code></pre> <p>Spacemacs: add to <code>dotspacemacs/user-config</code> in the Spacemacs configuration file.  Doom Emacs: add to <code>config.el</code> Doom configuration file.</p>"},{"location":"data-inspector/portal/#open-portal","title":"Open Portal","text":"<p><code>(require '[portal.api :as inspect])</code> once the REPL starts.</p> <p>For <code>inspector-portal-web</code> use <code>(require '[portal.web :as inspect])</code> instead</p> <p><code>(inspect/open)</code> to open the Portal inspector window in a browser (see portal themes)</p> <p><code>(add-tap #'portal/submit)</code> to add portal as a tap target</p>"},{"location":"data-inspector/portal/#use-portal-from-repl","title":"Use Portal from REPL","text":"<p>Portal functions can be called from the REPL prompt. When using Portal regularly, include code in a file, e.g. <code>dev/user.clj</code>  namespace to start a portal and add a tap source.  Use a rich comment form, <code>(comment ,,,)</code> to wrap the portal function calls if Portal should be launched manually by the developer.</p> <p>user namespace and REPL commands</p> <pre><code>(ns user\n  (:require [portal.api :as inspect]))\n\n(comment\n  ;; Open a portal inspector window\n  (inspect/open)\n  ;; Add portal as a tap&gt; target over nREPL connection\n  (add-tap portal.api/submit)\n  ;; Clear all values in the portal inspector window\n  (inspect/clear)\n  ;; Close the inspector\n  (inspect/close)\n  ) ;; End of rich comment block\n</code></pre>"},{"location":"data-inspector/portal/#open-portal-on-repl-startup","title":"Open Portal on REPL startup","text":"<p>Start the Portal inspector as soon as the REPL is started.  This works for a terminal REPL as well as clojure aware editors.</p> <p>Create a <code>dev/user.clj</code> source code file which requires the portal.api library, opens the inspector window and adds portal as  a tap source.</p> REPL ReloadedBasic Portal config <p>When using namespace reloading tools (clojure tools.namespace.repl, Integrant, etc.) it is advisable to exclude <code>dev</code> directory from the path to avoid launching multiple instances of Portal.</p> <p>Example</p> <pre><code>(ns user\n  (:require\n   [portal.api :as inspect]\n   [clojure.tools.namespace.repl :as namespace]))\n\n(println \"Set REPL refresh directories to \" (namespace/set-refresh-dirs \"src\" \"resources\"))\n</code></pre> <p>As a further precaution, check the Portal API <code>sessions</code> value to ensure Portal is not already running, preventing Portal running multiple times</p> <p>Example</p> <pre><code>(def portal-instance\n  (or (first (inspect/sessions))\n      (inspect/open {:portal.colors/theme :portal.colors/gruvbox})))\n</code></pre> <p>Example</p> <pre><code>(ns user\n  (:require [portal.api :as inspect]))\n\n;; ---------------------------------------------------------\n;; Open Portal window in browser with dark theme\n(inspect/open {:portal.colors/theme :portal.colors/gruvbox})\n;; Add portal as a tap&gt; target over nREPL connection\n(add-tap #'portal.api/submit)\n;; ---------------------------------------------------------\n(comment\n  (inspect/clear)  ; Clear all values in the portal inspector window\n  (inspect/close)  ; Close the inspector\n  ) ; End of rich comment block\n</code></pre> <p>Start a REPL using the <code>:repl/reloaded</code> or <code>:dev/reloaded</code> alias from  Practicalli Clojure CLI Config to include the <code>dev</code> directory on the path and the portal library.</p>"},{"location":"data-inspector/portal/#basic-use","title":"Basic use","text":"<p>The <code>tap&gt;</code> function sends data to Portal to be shown on the inspector window.</p> <pre><code>(tap&gt; {:accounts\n        [{:name \"jen\" :email \"jen@jen.com\"}\n        {:name \"sara\" :email \"sara@sara.com\"}]})\n</code></pre> <p>Use portal to navigate and inspect the details of the data sent to it via <code>tap&gt;</code>.</p> <p><code>(inspect/clear)</code> to clear all values from the portal inspector window.</p> <p><code>(inspect/close)</code> to close the inspector window.</p>"},{"location":"data-inspector/portal/#editor-commands","title":"Editor Commands","text":"<p>Control Portal from a Clojure Editor by wrapping the portal commands.</p> Emacs <p>Add helper functions to the Emacs configuration and add key bindings to call them.</p> <p>Emacs Configuration</p> <pre><code>;; def portal to the dev namespace to allow dereferencing via @dev/portal\n(defun portal.api/open ()\n  (interactive)\n  (cider-nrepl-sync-request:eval\n    \"(do (ns dev)\n         (def portal ((requiring-resolve 'portal.api/open)))\n         (add-tap (requiring-resolve 'portal.api/submit)))\"))\n\n(defun portal.api/clear ()\n  (interactive)\n  (cider-nrepl-sync-request:eval \"(portal.api/clear)\"))\n\n(defun portal.api/close ()\n  (interactive)\n  (cider-nrepl-sync-request:eval \"(portal.api/close)\"))\n</code></pre> <ul> <li>Spacemacs: add to <code>dotspacemacs/user-config</code> in the Spacemacs configuration file.</li> <li>Doom emacs: add to <code>config.el</code> Doom configuration file.</li> </ul> <p>Add key bindings to call the helper functions, ideally from the Clojure major mode menu.</p> SpacemacsDoom Emacs <p>Add key bindings specifically for Clojure mode, available via the <code>, d p</code> debug portal menu when a Clojure file (clj, edn, cljc, cljs) is open in the current buffer.</p> <p>Spacemacs Key bindings for Portal</p> <p>Add key bindings to Clojure major mode, e.g. , d p c to clear values from Portal Spacemacs Configuration - dotspacemacs/user-config<pre><code>(spacemacs/declare-prefix-for-mode 'clojure-mode \"dp\" \"Portal\")\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpp\" 'portal.api/open)\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpc\" 'portal.api/clear)\n(spacemacs/set-leader-keys-for-major-mode 'clojure-mode \"dpD\" 'portal.api/close)\n</code></pre></p> <p>Or add user key bindings to user menu, <code>SPC o</code> avoiding potential clash with Spacemacs Clojure layer key bindings. e.g. Space o p c to clear values from Portal Spacemacs Configuration - dotspacemacs/user-config<pre><code>(spacemacs/declare-prefix \"op\" \"Clojure Portal\")\n(spacemacs/set-leader-keys \"opp\" 'portal.api/open)\n(spacemacs/set-leader-keys \"opc\" 'portal.api/clear)\n(spacemacs/set-leader-keys \"opD\" 'portal.api/close)\n</code></pre></p> <p>Use the <code>map!</code> macro to add keys to the <code>clojure-mode-map</code>, using <code>:after</code> to ensure cider is loaded before binding the keys</p> <p>Doom Configuration</p> <pre><code>(map! :map clojure-mode-map\n      :n \"s-o\" #'portal.api/open\n      :n \"C-l\" #'portal.api/clear)\n</code></pre> <p>Practicalli Doom Emacs configuration</p> <p>Practicalli Doom Emacs config includes Portal key bindings in the Clojure major mode menu, under the debug menu. * <code>, d p o</code> to open portal * <code>, d p c</code> to clear results from portal</p> <pre><code>(map! :after cider\n      :map clojure-mode-map\n      :localleader\n      :desc \"REPL session\" \"'\" #'sesman-start\n\n      ;; Debug Clojure\n      (:prefix (\"d\" . \"debug/inspect\")\n       :desc \"debug\" \"d\" #'cider-debug-defun-at-point\n       (:prefix (\"i\" . \"inspect\")\n        :desc \"last expression\" \"e\" #'cider-inspect-last-sexp\n        :desc \"expression\" \"f\" #'cider-inspect-defun-at-point\n        :desc \"inspector\" \"i\" #'cider-inspect\n        :desc \"last result\" \"l\" #'cider-inspect-last-result\n        (:prefix (\"p\" . \"portal\")\n         :desc \"Clear\" \"c\" #'portal.api/clear\n         :desc \"Open\" \"D\" #'portal.api/close\n         :desc \"Open\" \"p\" #'portal.api/open)\n        :desc \"value\" \"v\" #'cider-inspect-expr))\n\n        ; truncated...\n        )\n</code></pre> <p>Practicalli Doom Emacs Config - +clojure.el</p> <p>Portal Documentation - Editors</p>"},{"location":"data-inspector/portal/#editor-nrepl-middleware","title":"Editor nREPL middleware","text":"<p><code>portal.nrepl/wrap-portal</code> sends every REPL evaluation to Portal over an nREPL connection, avoiding the need to wrap expressions with <code>tap&gt;</code>.</p>  Practicalli Clojure CLI ConfigAlias Definition <p>Start a REPL that includes the Portal nREPL middleware to send the result of every evaluation to portal.</p> <ul> <li><code>:repl/reloaded</code> - rich terminal UI with portal and REPL Reloaded tools</li> <li><code>:repl/inspect</code> - basic terminal UI with portal</li> </ul> <p><code>:repl/inspect</code> to start a terminal REPL with nREPL support for Clojure editor connection and portal libraries and middleware that will send all evaluations to portal once added as a tap source. !!!! EXAMPLE \"User deps.edn\"     <pre><code>:repl/inspect\n{:extra-deps\n {nrepl/nrepl          {:mvn/version \"1.0.0\"}\n  cider/cider-nrepl    {:mvn/version \"0.30.0\"}\n  djblue/portal        {:mvn/version \"0.40.0\"}\n  clj-commons/clj-yaml {:mvn/version \"0.7.0\"}}\n :main-opts [\"-m\" \"nrepl.cmdline\"\n             \"--middleware\"\n             \"[cider.nrepl/cider-middleware,portal.nrepl/wrap-portal]\"]}\n</code></pre></p> <p>Start a REPL with <code>:repl/reloaded</code> or 'repl/inspect'</p> <pre><code>clojure -M:repl/reloaded\n</code></pre> <p>Start Portal User Interface and add portal as a tap target using the <code>portal.api/submit</code> function to send all evaluated code to Portal</p> <p>Clear results to keep history manageable</p> <p>Use the Portal API <code>clear</code> function to remove all existing results in Portal</p>"},{"location":"data-inspector/portal/#tap-logs-to-portal","title":"Tap Logs to Portal","text":"<p>Using a custom mulog publisher, all event logs can be automatically sent to portal.</p> <p>mulog tap publisher</p> <pre><code>;; ---------------------------------------------------------\n;; Mulog Custom Publishers\n;; - tap publisher for use with Portal and other tap sources\n;; ---------------------------------------------------------\n(ns mulog-publisher\n  (:require\n   ;; [com.brunobonacci.mulog :as mulog]\n   [com.brunobonacci.mulog.buffer :as mulog-buffer]\n   [portal.api :as p]))\n\n(deftype TapPublisher [buffer transform]\n  com.brunobonacci.mulog.publisher.PPublisher\n  (agent-buffer [_] buffer)\n  (publish-delay [_] 200)\n  (publish [_ buffer]\n    (doseq [item (transform (map second (mulog-buffer/items buffer)))]\n      (tap&gt; item))\n    (mulog-buffer/clear buffer)))\n\n(defn tap\n  [{:keys [transform] :as _config}]\n  (TapPublisher. (mulog-buffer/agent-buffer 10000) (or transform identity)))\n</code></pre> <p>Require the <code>mulog-publisher</code> namespace and mulog library in the <code>user</code> ns expression</p> <p>Require <code>mulog-publisher</code> namespace</p> <pre><code>(ns user\n  \"Tools for REPL Driven Development\"\n  (:require\n   [com.brunobonacci.mulog :as mulog]\n   [mulog-publisher]))\n</code></pre> <p>Start the publisher, optionally setting a global context for events first</p> <p>Set values for all mulog events and start custom mulog publisher</p> <pre><code>;; ---------------------------------------------------------\n;; Mulog events and publishing\n\n;; set event global context - information added to every event for REPL workflow\n(mulog/set-global-context! {:app-name \"Practicalli Service\",\n                            :version \"0.1.0\", :env \"dev\"})\n\n(def mulog-tap-publisher\n  \"Start mulog custom tap publisher to send all events to Portal\n  and other tap sources\n  `mulog-tap-publisher` to stop publisher\"\n  (mulog/start-publisher!\n    {:type :custom, :fqn-function \"mulog-publisher/tap\"}))\n;; ---------------------------------------------------------\n</code></pre> <p>Mulog events are now sent to portal when evaluated</p> <pre><code>    (mulog/log ::repl-state ::ns (ns-publics *ns*))\n</code></pre> <p>Stop the mulog publisher by calling the reference it returns, i.e. mulog-tap-publisher</p> <p>Function to stop mulog tap publisher</p> <pre><code>(defn mulog-tap-stop\n \"Stop mulog tap publisher to ensure multiple publishers are not started\n Recommended before using `(restart)` or evaluating the `user` namespace\"\n  [] (mulog-tap-publisher))\n</code></pre>"},{"location":"data-inspector/portal/#references","title":"References","text":"<p> Portal Documentation - clj-docs</p>"},{"location":"data-structures/","title":"Data structures","text":"<p>Clojure is a very data-centric language.  <code>clojure.core</code> contains a great number of functions for manipulating data structures, especially the immutable built in data structures, referred to generically as collections.</p> <p>Collections can take any types of elements and types can be mixed.  Collections can even have other collections as an element.</p> <p>Collections are passed as arguments to function (either in part or in full) and functions often return collections as a result.</p>"},{"location":"data-structures/#built-in-collections","title":"Built-in collections","text":"<p>Values can be represented as a collection of discrete pieces of data: number, string, boolean value.</p> <p>Clojure has great facilities for working with collections of data, providing many types of data structures and a uniform way to use all of these data structures.</p> <p>The 4 commonly used built-in data structures</p> Name syntax Description list <code>()</code> A linked list, optomised for sequential access from the front (head) vector <code>[]</code> An indexed array optimised for random access hash-map <code>{:key \"value\"}</code> Associative collection of key / value pairs, keys must be unique. Keys are the index set <code>#{}</code> A unique set of values <p>Vector and hash-map are the most commonly collections used to model information with Clojure.</p> <p>Lists are not explicitly used to model data, although data may be returned by a function as a list (referred to as a sequence)</p>"},{"location":"data-structures/#collection-characteristics","title":"Collection Characteristics","text":"<p>Clojure data structure share the following characteristics:</p> <ul> <li>Immutable - once a data structure is defined it cannot be changed</li> <li>Persistent - functions may return an altered copy of a data structure which will share common values with the original data structure for efficient memory use (structural sharing)</li> <li>Dynamically typed - a data structure can contain any value, including functions (as they evaluate to a value) and other data structures (nested data structures)</li> </ul> <p>This section will cover the Clojure built in persistent data structures in more detail.</p>"},{"location":"data-structures/#common-data-structures","title":"Common Data Structures","text":"<p>Simple data</p> <p>(def name value)</p> <p>Sequential data</p> <p>(list ...) sequence - always processed sequentially</p> <p>(vector) sequencw with randon access</p> <p>Dictionary</p> <p>(key value  key1 value  key2 value)</p> <p>Connverting data, data decoder/encoder, state machine, etc</p> <p>Data set</p> <pre><code>(def name\n  [{:identical-keys \"with evolving values\"}\n   {:identical-keys \"values differ from each other\"}\n   {:identical-keys \"values collectively provide meaning\"}])\n</code></pre> <p>Weather monitoring data, bank transactions, stock exchange rates, etc</p>"},{"location":"data-structures/#hierarchical-data","title":"Hierarchical data","text":"<pre><code>(def name\n  {:simple-key value\n   :composite-key {:nested-key value}\n   :deeper-composite-key {:nested-key {:deeper-nested-key value}}})\n</code></pre> <p>representing state, structure of a website Starwars example,</p> <p>walk the hierarchy to get the appropriate values</p> <p>extract only the values required by a function and pass as arguments</p> <p>hierachiecy can become too complex to manage, the flatest possible structure is usually simpler to work with (transform)</p>"},{"location":"data-structures/alternatives/","title":"Alternative data structures","text":"<p>Whist list, vector, hash-map and set are by far the most commonly used data structures, Clojure has many others of interest.</p>"},{"location":"data-structures/alternatives/#variations-on-hash-maps","title":"Variations on hash-maps","text":""},{"location":"data-structures/alternatives/#variations-on-sets","title":"Variations on sets","text":"<p>ordered-set</p>"},{"location":"data-structures/list/","title":"List","text":"<p>The list is used extensively in Clojure, it is a List (List Processing) language after all.  The unique thing about lists is that the first element is always evaluated as a function call, therefore lists are most commonly used for defining and calling functions.</p> <p>Lists are sometimes used as a data structure and have a sequential lookup time.  A list can hold any valid types of data, from numbers and strings to other data structures such as vectors, maps and sets.  Types can be mix as Clojure will dynamically type each element as its evaluated.</p> <p>Its more common to use vectors and maps which typically offer quicker access as they can be looked up via an index or key.</p> <p>Note Explore the list data structure and discover which line of code fails.  Try work out why that line of code fails.</p> <pre><code>(list 1 2 3 4)\n(list -1 -0.234 0 1.3 8/5 3.1415926)\n(list \"cat\" \"dog\" \"rabbit\" \"fish\")\n(list :cat 1 \"fish\" 22/7 (str \"fish\" \"n\" \"chips\"))\n(list 1 2 \"three\" [4] five '(6 7 8 9))\n(list )\n\n( 1 2 3 4)\n\n(quote (1 2 3 4))\n'(1 2 3 4)\n\n;; Duplicate elements in a list ?\n(list 1 2 3 4 1)\n(list \"one\" \"two\" \"one\")\n(list :fred :barney :fred)\n</code></pre> <p>We can create a list using the <code>list</code> function</p> <pre><code>(list 1 2 3 4)\n</code></pre> <p>This evaluates to <code>(1 2 3 4)</code></p> <p>We can give this result a name</p> <pre><code>(def my-list (list 1 2 3 4))\n</code></pre> <p>Then when we evaluate <code>my-list</code> it will return the list as a result</p> <p>However, if we create a list directly by using <code>(1 2 3 4)</code>, this will fail when evaluated as <code>1</code> is not a function.  So when we define a data structure as a list we need to use the <code>quote</code> function or ' syntax</p> <pre><code>(quote (1 2 3 4))\n'(1 2 3 4)\n</code></pre>"},{"location":"data-structures/list/#hintfirst-element-of-a-list-is-a-function-call","title":"Hint::First element of a list is a function call","text":"<p>The first element of a list is evaluated as a function call, unless the list is wrapped in a quote function</p>"},{"location":"data-structures/list/#testing-for-a-list","title":"Testing for a List","text":"<p>When is a list not a <code>list?</code>.  Lists are sometimes created as other types if they are created in ways other than using the <code>list</code> function.  If you want to know if something is list like, then you can use the <code>seq?</code> function.  If you test with the <code>list?</code> function and that returns false, you can use the <code>type</code> function to see what its real type is.</p> <p>See more about the types that list-like structures actually are in the article: What is a list? The ultimate predicate showdown</p>"},{"location":"data-structures/naming/","title":"Naming data structures","text":"<p>We have seen that defining things is as simple as giving a name to a value using the <code>def</code> function.  It is the same for the Clojure data structures and any other values.</p> <pre><code>(def people [\"Jane Doe\" \"Samuel Peeps\"])\n</code></pre> <p>Names are of course case sensitive, so Person is not the same as person</p> <pre><code>(def Person \"James Doh\" \"Sam Stare\")\n</code></pre> <p>Clojure uses dynamic typing, this means its trivial to mix and match different kinds of data.  Here we are defining a name for a vector, which contains numbers, a string and name of another def.</p> <pre><code>(def my-data [1 2 3 \"frog\" person])\n\nmy-data\n</code></pre>"},{"location":"data-structures/naming/#data-structures-are-immutable-names-are-mutable","title":"Data structures are immutable, names are mutable","text":"<p>You can dynamically re-define a name to points to a different value.</p> <p>Hint This re-definition (or rebinding) of names to new values is typically used only during the development of your code, especially in REPL driven development.</p> <pre><code>(def my-data [1 2 3 4 5 \"frog\" person])\n</code></pre> <p>The original value that defined my-data remains unchanged (its immutable), so anything using that value remains unaffected.  Essentially we are re-mapping my-data to a new value.</p> <p>Lets define a name to point to a list of numbers</p> <pre><code>(def my-list '(1 2 3))\n</code></pre> <p>We are returned that list of numbers when we evaluate the name</p> <pre><code>my-list\n</code></pre> <p>We can use the cons function to add a number to our list, however because lists are immutable, rather than changing the original list, a new one is returned.  So if we want to keep on referring to our \"changed\" list, we need to give it a name</p> <pre><code>(def my-list-updated (cons 4 my-list))\n</code></pre> <p>As you can see we have not changed the original list</p> <pre><code>my-list\n</code></pre> <p>;; The new list does have the change though.</p> <pre><code>my-list-updated\n</code></pre> <p>You could therefore give the impression of mutable state by applying a function to data structure and redefining the original name to point to the resulting data structure.</p> <p>Hint In practice, the ability to redefine functions and data structures live helps you develop your application quickly in the REPL.</p> <p>In production you typical do not redefine functions or data structures in a live running application.  That could be part of a new release of your application though.</p> <pre><code>(def my-list (cons 5 my-list))\n</code></pre> <p>So now when we evaluate the original name, we get the updated list</p> <pre><code>my-list\n</code></pre>"},{"location":"data-structures/naming/#naming-scope","title":"Naming Scope","text":"<p>All def names are publicly available via their namespace.  As def values are immutable, then keeping things private is of less concern than languages built around Object Oriented design.</p> <p>Private definitions syntax can be used to limit the access to def names to the namespace they are declared in.</p> <p>To limit the scope of a def, add the :private true metadata key value pair.</p> <pre><code>(def ^{:private true} some-var :value)\n\n(def ^:private some-var :value)\n</code></pre> <p>The second form is syntax sugar for the first one.</p> <p>You could also define a macro for def-</p> <pre><code>(defmacro def- [item value]\n  `(def ^{:private true} ~item ~value)\n)\n</code></pre> <p>You would then use this macro as follows:</p> <pre><code>(def- private-definition \"This is only accessible in the namespace\")\n</code></pre>"},{"location":"data-structures/pretty-printing/","title":"Pretty Printing data structures","text":"<p>Data structures containing small amounts of data are quite human readable, although can benefit from pretty printing to make them very easy for humans to read.</p> <p>The larger a data structure becomes, or if a data structure is nested, then there are tools to print out ascii views of the data structures.</p>"},{"location":"data-structures/pretty-printing/#pretty-print-hash-maps","title":"Pretty print hash-maps","text":"<pre><code>(clojure.pprint/pprint\n  {:account-id 232443344 :account-name \"Jenny Jetpack\" :balance 9999 :last-update \"2021-12-12\" :credit-score :aa} )\n</code></pre> <p>Each key is printed on a new line, making the hash-map easier to read, especially when there are a large number of keys</p> <pre><code>{:account-id 232443344,\n :account-name \"Jenny Jetpack\",\n :balance 9999,\n :last-update \"2021-12-12\",\n :credit-score :aa}\n</code></pre> <p>Clojure aware editors can also have an align option when formatting hash-maps, making the results easier to read</p> <pre><code>{:account-id   232443344,\n :account-name \"Jenny Jetpack\",\n :balance      9999,\n :last-update  \"2021-12-12\",\n :credit-score :aa}\n</code></pre>"},{"location":"data-structures/pretty-printing/#hintpretty-print-evaluation-results","title":"Hint::Pretty Print evaluation results","text":"<p>Clojure aware editors should allow the pretty printing of the evaluation results.</p>"},{"location":"data-structures/pretty-printing/#print-table-of-nested-data-structures","title":"Print Table of nested data structures","text":"<p>Nested data structures can also be shown as a table, especially the common approach of using a vector of hash-maps where each map has the same keys</p> <pre><code>(clojure.pprint/print-table\n  [{:location \"Scotland\" :total-cases 42826 :total-mortality 9202}\n   {:location \"Wales\" :total-cases 50876 :total-mortality 1202}\n   {:location \"England\" :total-cases 5440876 :total-mortality 200202}])\n</code></pre> <pre><code>| :location | :total-cases | :total-mortality |\n|-----------+--------------+------------------|\n|  Scotland |        42826 |             9202 |\n|     Wales |        50876 |             1202 |\n|   England |      5440876 |           200202 |\n</code></pre>"},{"location":"data-structures/pretty-printing/#references","title":"References","text":"<p>Data browsers (Cider Inspector, Portal, Reveal Free) are very useful for larger and nested data structures.</p>"},{"location":"data-structures/set/","title":"Set","text":"<p>A Clojure set is a persistent data structure that holds a unique set of elements.  Again the elements can be of any type, however each element must be unique for a valid set.</p> <p>Note Explore creating sets from existing collections.  Notice what happens if you have duplicate values in the collection.  Define sets directly using the <code>#{}</code> notation and see what happens if there are duplicate values.</p> <pre><code>(set `(1 2 3 4))\n(set `(1 2 1 2 3 4))\n\n#{1 2 3 4}\n#{:a :b :c :d}\n;; duplicate key error\n#{1 2 3 4 1}\n</code></pre>"},{"location":"data-structures/set/#unique-but-not-ordered","title":"Unique but not ordered","text":"<p>A set is not ordered by the values it contains.  If you need a sorted set then you can use the <code>sorted-set</code> function when creating a new set.  Or you can run</p> <pre><code>(sorted-set 1 4 0 2 9 3 5 3 0 2 7 6 5 5 3 8)\n\n(sort [9 8 7 6 5])\n(sort-by )\n</code></pre>"},{"location":"data-structures/set/#looking-up-values-in-a-set","title":"Looking up values in a set","text":"<pre><code>(#{:a :b :c} :c)\n(#{:a :b :c} :z)\n</code></pre> <p>Sets can also use the <code>contains?</code> function to see if a value exists in a set</p> <pre><code>(contains?\n  #{\"Palpatine\" \"Darth Vader\" \"Boba Fett\" \"Darth Tyranus\"}\n  \"Darth Vader\")\n</code></pre>"},{"location":"data-structures/shared-memory/","title":"Shared memory with Persistent data structures","text":"<p>The Clojure data structures are immutable, so they initially seem similar to constants rather than variables.  Once a collection is created, it cannot be changed.  Any functions that run on a collection do not change the collection, instead they return a new collection with the respective changes.</p> <p>Creating a new collection each time may seem inefficient, however, the persistent collections use a sharing model.  When a new collection is created, it links to all the relevant elements of the original collection and adds any new elements.</p> <p></p> <p>Hint Read the InfoQ article on An In-Depth Look at Clojure Collections.</p>"},{"location":"data-structures/vector/","title":"Vector","text":"<p>Vectors are an indexed sequential collections of data, basically the same as arrays in other languages.  However, there are several differences.  The index for a vector starts at 0, just like arrays in other languages.</p> <p></p> <p>Vectors are written using square brackets <code>[]</code> with any number of pieces of data inside them, separated by spaces.</p> <p>Note Experiment with creating vectors for your data structures</p> <pre><code>(vector 1 2 3 4)\n[1 2 3 4 5]\n[56.9 60.2 61.8 63.1 54.3 66.4 66.5 68.1 70.2 69.2 63.1 57.1]\n[]\n\n(def pi 3.1435893)\n[1 2.4 pi 11/4 5.0 6 7]\n[:cat :dog :rabbit :fish]\n[{:cat 1} \"fish\" \"potatoes\" \"oil\" (str \"who ate my\" \"fish n chips\")]\n\n;; Include other data structures in vectors, in this example a list is an element of the vector\n[1 2 3 '(4 5 6)]\n\n;; Are duplicate elements allowed ?\n[1 2 3 4 1]\n</code></pre> <p>Note What can you do with vectors? Vectors are easy to add more items to, delete items from, or pull arbitrary items out of. Here are some functions that operate on vectors.</p> <pre><code>(vector? [5 10 15])\n(= [] [])\n(= [] [1])\n\n(first [5 10 15])\n(rest [5 10 15])\n(nth [5 10 15] 1)\n(count [5 10 15])\n\n(conj [5 10] 15)\n</code></pre> <p>Hint When a function is effectively asking if a value is true or false, its referred to as a predicate function.  Its common practice in Clojure to place a <code>?</code> at the end of that functions name.</p>"},{"location":"data-structures/vector/#lookup-data-from-a-vector","title":"Lookup data from a Vector","text":"<pre><code>([1 2 3] 1)\n\n;; ([1 2 3] 1 2)  ;; wrong number of arguments, vectors behaving as a function expect one parameter\n\n;; ((1 2 3) 1) ;; you cant treat lists in the same way, there is another approach - assoc\n</code></pre>"},{"location":"data-structures/vector/#changing-vectors","title":"Changing vectors","text":"<p>The next two functions are used to make new vectors. The <code>vector</code> function takes any number of items and puts them in a new vector.</p> <p><code>conj</code> takes a vector and an item and returns a new vector with that item added to the end. The function name is taken from the verb \"conjugate\", meaning \"to join together.</p> <p>Remember that  collections in Clojure are immutable, so when we say that a function \"adds to\" or \"removes from\" a collection, what we mean is that the function returns a new collection with an item added or removed.</p> <p>Note Using one or more vectors, create a data structure of the high temperatures for the next 7 days in your area. Use the <code>nth</code> function to get the high temperature for next Friday</p>"},{"location":"data-structures/hash-maps/","title":"Data Structures: Hash-maps","text":"<p>Associative collection of key value pairs</p> <p>Useful for defining self-describing structured data (assuming meaningful key names are used)</p> <p>A map is a key / value pair data structure.  Keys are usually defined using a keyword, although they can be strings or anything else.</p> <p>Keywords point to themselves, so using them for the keys makes it very easy to get values out of the map, or for updating existing values in the map.</p> <p>Note Explore creating maps</p> <pre><code>{:key \"value\"}\n{:key :value}\n{\"key\" \"value\"}\n(\"key\" :value)\n(:meaining-of-life 42)\n{:a 1 :b 2 :c 3}\n{:monday 1 :tuesday 2 :wednesday 3 :thursday 4 :friday 5 :saturday 6 :sunday 7}\n{1 \"Monday\" 2 \"Tuesday\" 3 \"Wednesday\" 4 \"Thursday\" 5 \"Friday\" 6 \"Saturday\" 7 \"Sunday\"}\n</code></pre>"},{"location":"data-structures/hash-maps/#hintcomma-characters-are-treated-as-white-space","title":"Hint::Comma characters are treated as white-space","text":"<p>The comma character is rarely used in Clojure hash-maps as it is ignored by Clojure.  When coming from other languages, it may be initially comforting to include commas.</p>"},{"location":"data-structures/hash-maps/#nested-data-models","title":"Nested data models","text":"<p>nested maps to create a hierarchy or path for data.  This can add more context to the overall design</p> <p>various types of data</p>"},{"location":"data-structures/hash-maps/#hintone-data-structure-to-rule-them-all","title":"Hint::One data structure to rule them all","text":"<p>It is preferred to have a single data structure to model the data of a system, which is them used by all the functions of that system.  An example is in the state used for an application, e.g. Practicalli website practicalli.data namespace</p> <p>If there is no logical connection between data across a system, then data should be grouped into one structure per namespace as a minimal approach.</p>"},{"location":"data-structures/hash-maps/#example-use-data-sets","title":"Example use: Data sets","text":"<p>A collection of maps which have the same form, e.g. a vector of hash-maps with the same keys</p> <p>Example: meteorological recordings</p> <pre><code>(def recording-station-876WA\n [{:timestamp \"2021-12-01T12:00\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.4 :rainfail 0.1 :uv-level 0.4}\n  {:timestamp \"2021-12-01T12:10\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.6 :rainfail 0.1 :uv-level 0.45}\n  {:timestamp \"2021-12-01T12:00\" :location {:latitude 24.3453434 :longitude 10.348888} :temperature 12.9 :rainfail 0.1 :uv-level 0.5}])\n</code></pre> <p>Providing a collection of consistent hash-map data structures is very easy to work with in Clojure.</p> <p><code>reduce</code>, <code>filter</code> and <code>map</code> functions can easily process this form of data as part of algorithms to interpret the meaning from a data set.</p> <p>As each recording station creates the same types of data, then they can be merged by including the recording station id in the map</p>"},{"location":"data-structures/hash-maps/access/","title":"Accessing hash-maps","text":"<p>The values in a hash-map can be accessed in multiple ways</p> <ul> <li><code>get</code></li> <li><code>get-in</code></li> <li><code>contains?</code></li> <li>using hash-map as a function</li> <li>use :keyword as a function</li> <li>threading hash-map through one or more keys</li> </ul> <p>Clojure provides a get function that returns the value mapped to a key in a set or map.</p>"},{"location":"data-structures/hash-maps/access/#get-and-get-in-functions","title":"get and get-in functions","text":"<p><code>get</code> is a very explicitly named function that makes its purpose very clear.  The <code>get</code> function works regardless of the type of keys used in the hash-map.</p> <p><code>(get map key)</code></p> <p><code>get-in</code> has the same quality, for use with nested hash-maps.</p> <pre><code>(get-in nested-map [:keys :path])\n</code></pre> <pre><code>(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [\"scores\" \"FSU\"])\n;;=&gt; 31\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [\"scores\"])\n;;=&gt; {\"FSU\" 31, \"UF\" 7}\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} [])\n;;=&gt; {\"timestamp\" 1291578985220, \"scores\" {\"FSU\" 31, \"UF\" 7}}\n\n(get-in {\"timestamp\" 1291578985220 \"scores\" {\"FSU\" 31 \"UF\" 7}} nil)\n;;=&gt; {\"timestamp\" 1291578985220, \"scores\" {\"FSU\" 31, \"UF\" 7}}\n</code></pre>"},{"location":"data-structures/hash-maps/access/#hintmissing-or-incorrect-key","title":"Hint::missing or incorrect key","text":"<p>If the key in the path is missing or the path is missing (or nil) then <code>get-in</code> will return more of the hash-map than expected.</p>"},{"location":"data-structures/hash-maps/access/#using-hash-map-as-a-function","title":"Using hash-map as a function","text":"<p>A hash-map (and list, vector, set) can be called as a function with a key as the argument.  This provides a more terse expression than using <code>get</code> and also works irrespective of key types used.</p> <p>Passing the key <code>:star-wars</code> to the hash-map returns the value associated with that key</p> <pre><code>({:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}} :star-wars)\n</code></pre> <p>A nested hash-map (containing other hash-maps) can be accessed via multiple nested calls to the returned values.</p> <pre><code>((({:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}} :star-wars) :characters) :jedi)\n</code></pre>"},{"location":"data-structures/hash-maps/access/#keyword-key-as-a-function","title":"keyword key as a function","text":"<p>A keyword can be called as a function, taking a hash-map as an argument</p> <pre><code>(:star-wars {:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}})\n</code></pre> <p>A nested hash-map (containing other hash-maps) can be accessed via multiple nested calls to the returned values.</p> <pre><code>(:jedi (:characters (:star-wars {:star-wars {:characters {:jedi [\"Luke\" \"Obiwan\"]}}})))\n</code></pre>"},{"location":"data-structures/hash-maps/access/#threading-macro","title":"Threading macro","text":"<p>Using keyword keys as functions, the thread macros provide a consistent approach to accessing hash-map data</p> <p>The hash-map is passed through one or more keyword keys, so obtaining values from a flat or nested hash-map is just the same.</p> <pre><code>(-&gt; hash-map\n    :keyword1\n    ,,,)\n</code></pre> <p>If the keys are a type other than keywords, then a get function would be required for accessing the hash-map.</p> <pre><code>(-&gt; hash-maps (get \"scores\") (get \"FSU\"))\n</code></pre> <p>As part of a processing pipeline, taking specific values from a JSON file of association football match statistics</p> <pre><code>(-&gt; match-statistics.json\n    (clojure.data.json/read-str :key-fn keyword)\n    :totals\n    :goals-home-team)\n</code></pre>"},{"location":"data-structures/hash-maps/access/#checking-a-key-or-value-exists-in-a-hash-map","title":"Checking a key or value exists in a hash-map","text":"<p><code>keys</code> function will return a collection of the keys contained in a map.  <code>vals</code> returns a collection of the values</p> <p>is in a map or set. In general I use the value returned from a map or set to determine if a key exists - the following snippet uses that pattern.</p> <p>Check if a key has a specific value</p> <pre><code>(if (star-wars-map :space-ships)\n  (do-true-behaviours)\n  (do-false-behaviours))\n</code></pre> <p>Check a key has a specific value and also use that value</p> <p>TODO: is this a good case for if-lets</p> <p>This pattern fails if the value of :key is nil.</p>"},{"location":"data-structures/hash-maps/access/#contains-and-some","title":"contains? and some","text":"<p><code>contains?</code> checks for the index of a collection.  The index of a hash-map is the keys it contains</p> <p><code>some</code> will check for a value in a collection</p> <pre><code>(def recipe-map {:ingredients \"tofu\"})\n\n(contains? recipe-map :ingredients)\n;; =&gt; true\n\n(some #{\"tofu\"} recipe-map)\n;; =&gt; nil\n\n(vals recipe-map)\n;; =&gt; (\"tofu\")\n\n(some #{\"tofu\"} (vals recipe-map))\n;; =&gt; \"tofu\"\n</code></pre> <p>The key is contained as part of the hash-map index, irrespective of the value associated with that key (so long as there is a legal value associate with the key).</p> <pre><code>(contains? {:totals nil} :totals)\n</code></pre>"},{"location":"data-structures/hash-maps/accessing-nested-hash-maps/","title":"Accessing Nested Hash-maps","text":"<p>Its also quite common to have maps made up of other maps, maps of vectors or vectors of maps.</p> <p>Now we can refer to the characters using keywords.  Using the get function we return all the information about Luke</p> <pre><code>(get star-wars-characters :luke)\n(get (get star-wars-characters :luke) :fullname)\n</code></pre> <p>By wrapping the get function around our first, we can get a specific piece of information about Luke.  There is also the get-in function that makes the syntax a little easier to read</p> <pre><code>(get-in star-wars-characters [:luke :fullname])\n(get-in star-wars-characters [:vader :fullname])\n</code></pre> <p>Or if you want the data driven approach, just talk to the map directly</p> <pre><code>(star-wars-characters :luke)\n(:fullname (:luke star-wars-characters))\n(:skill (:luke star-wars-characters))\n\n(star-wars-characters :vader)\n(:skill (:vader star-wars-characters))\n(:fullname (:vader star-wars-characters))\n</code></pre> <p>And finally we can also use the threading macro to minimise our code further</p> <pre><code>(-&gt; star-wars-characters\n    :luke)\n\n(-&gt; star-wars-characters\n    :luke\n    :fullname)\n\n(-&gt; star-wars-characters\n    :luke\n    :skill)\n</code></pre> <p>This technique is called destructuring.  Find out more on Destructuring</p> <p>Duplicate keys in a map are not allowed, so the following maps...</p> <pre><code>{\"fish\" \"battered\" \"chips\" \"fried\" \"fish\" \"battered and fried\"}\n{:fish \"battered\" :chips \"fried\" :fish \"battered &amp; fried\"}\n\n;; ...throw duplicate key errors\n\n;; Duplicate values are okay though\n{:fish \"fried\" :chips \"fried\" :peas \"mushy\"}\n</code></pre>"},{"location":"data-structures/hash-maps/create/","title":"Creating Hash-maps","text":"<p>Hash-maps can be defined literally using <code>{}</code> and including zero or more key / value pairs.  Keys and values can be any legal Clojure type.</p> <p>Keywords are very commonly used for keys as they provide a convenient way to look up values.</p>"},{"location":"data-structures/hash-maps/create/#literal-hash-map-examples","title":"Literal hash-map examples","text":"<p>A hash-map defining Obi-wan, a character from the Star Wars universe.</p> <pre><code>{:name \"Obi-wan Kenobi\" :homeworld \"Stewjon\"}\n</code></pre> <p>A hash-map defining Leia, another character from the Star Wars with additional information</p> <pre><code>{:name \"Leia Skywalker\" :homeworld \"Alderaan\" :birthplace \"Polis Massa\"}\n</code></pre> <p>Use <code>def</code> to bind a name to a hash-map, making it easier to pass the map to a function as an argument.</p> <pre><code>(def luke {:name \"Luke Skywalker\" :homeworld \"Tatooine\" :birthplace \"Polis Massa\"})\n</code></pre>"},{"location":"data-structures/hash-maps/create/#data-set-of-maps","title":"Data set of maps","text":"<p>Create a data set by defining a vector of hash-maps</p> <pre><code>[{:name \"Obi-wan Kenobi\"  :homeworld \"Stewjon\"   :occupation \"Jedi\"}\n {:name \"Jyn Erso\"        :homeworld \"Vallt\"     :occupation \"Soldier\"}\n {:name \"Leia Skywalker\"  :homeworld \"Alderaan\"  :occupation \"Senator\"}\n {:name \"Luke Skywalker\"  :homeworld \"Tatooine\"  :occupation \"Jedi\"}\n {:name \"Qui-Gon Jinn\"    :homeworld \"Coruscant\" :occupation \"Jedi\"}\n {:name \"Padm\u00e9 Amidala\"   :homeworld \"Naboo\"     :occupation \"Senator\"}\n {:name \"Sheev Palpatine\" :homeworld \"Naboo\"     :occupation \"Supreme Chancellor\"}]\n</code></pre>"},{"location":"data-structures/hash-maps/create/#example-nested-hash-maps","title":"Example: nested hash-maps","text":"<p>Create a map to represent the world of Star Wars, including various characters &amp; ships, indicating the factions that characters and ships belong to.</p> <p>Individual Star Wars characters can be defined using a map of maps</p> <pre><code> {:luke   {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n  :vader  {:name \"Darth Vader\"    :skill \"Breaking the rules and peoples hearts\"}\n  :jarjar {:name \"JarJar Binks\"   :skill \"Failing upwards\"}}\n</code></pre> <p>Hash-maps can also use other collections as values</p> <pre><code>{:characters\n  {:jedi   [\"Luke Skywalker\" \"Obiwan Kenobi\"]\n   :sith   [\"Darth Vader\" \"Darth Sideous\"]\n   :droids [\"C3P0\" \"R2D2\" \"BB8\"]}\n :ships\n   {:rebel-alliance  [\"Millennium Falcon\" \"X-wing fighter\"]\n    :imperial-empire [\"Intergalactic Cruiser\" \"Destroyer\"\n                      \"Im just making these up now\"]}}\n</code></pre> <p>Use the def function to bind a name to the Star Wars character information, making it easier to pass to several functions</p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Breaking the rules and peoples hearts\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Failing upwards\"}})\n</code></pre>"},{"location":"data-structures/hash-maps/create/#generating-hash-maps","title":"Generating hash-maps","text":"<p><code>hash-map</code> is a clojure.core function that returns a hash-map of the given arguments, or an empty hash-map, <code>{}</code>, if no arguments are given.</p> <p>Arguments should be key-value pairs, otherwise the function will return nil</p>"},{"location":"data-structures/hash-maps/create/#converting-collections-to-hash-maps","title":"Converting collections to hash-maps","text":"<pre><code>(apply hash-map [:a 1 :b 2])\n;;=&gt; {:b 2 :a 1}\n</code></pre> <p>Order of keys in a hash-map is not guaranteed.  However, order of keys should be irrelevant as the keys are unique within a map.</p> <pre><code>(into {} ,,,)\n</code></pre> <p>map</p> <p>reduce</p> <p>merge returns a hash-map that is a merging of the key value pairs from all maps, for any duplicate keys the value from the last key (left to right) is used</p>"},{"location":"data-structures/hash-maps/create/#setting-default-values","title":"Setting default values","text":"<p>Calling a function with a hash-map as an argument is a flexible way to design the API of a namespace and Clojure application in general.</p> <p>As functions are talking a map, a function call with fewer or more keys than needed will still result in a successful call (alhtough results could be interesting)</p> <p>If fewer keys are passed then defaults can be set.</p> <p><code>merge</code> can be used to ensure any required keys with default values are always present, and still over-ridden by keys passed in as an argument</p> <p><code>merge</code> should passed the default key values first, with the argument map merged on top. This ensures all keys are present and that the argument values are used if duplicate keys exist between the maps.</p> <pre><code>(merge {:option1 \"default-value\" :option2 \"default-value\"}\n       {:option1 \"custom-value\"})\n;;=&gt; {:option1 \"custom-value\" :option2 \"default-value\"}\n</code></pre> <p>The <code>merge</code> function can be used in a function to return the merged map of default and argument values When a function has a number of options  with default values.</p> <pre><code>(defn parse-cli-tool-options\n  \"Return the merged default options with any provided as a hash-map argument\"\n[arguments]\n   (merge {:replace false :report true :paths [\".\"]}\n          arguments))\n\n(parse-cli-tool-options {:paths [\"src\" \"test\"] :report false})\n;; =&gt; {:replace false, :report false, :paths [\"src\" \"test\"]}\n</code></pre> <p>If an empty hash-map is sent as an argument, the default values are returned</p> <pre><code>(parse-cli-tool-options {})\n;; =&gt; {:replace false, :report true, :paths [\".\"]}\n</code></pre> <p>zipmap</p> <pre><code>(zipmap [:a :b :c] [1 2 3])\n;; =&gt; {:a 1, :b 2, :c 3}\n</code></pre>"},{"location":"data-structures/hash-maps/create/#custom-merging-with-a-function","title":"Custom merging with a function","text":""},{"location":"data-structures/hash-maps/create/#create-a-sub-set-of-existing-map","title":"Create a sub-set of existing map","text":""},{"location":"data-structures/hash-maps/create/#filter","title":"filter","text":"<p>Create a sub-set of an existing map</p> <p>;; #61 - Map Construction ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Difficulty: Easy ;; Topics: core-functions ;; Special Restrictions: zipmap</p> <p>;; Write a function which takes a vector of keys and a vector of values and constructs a map from them.</p> <p>;; Tests (= ([:a :b :c] [1 2 3]) {:a 1, :b 2, :c 3}) (= ( [1 2 3 4] [\"one\" \"two\" \"three\"]) {1 \"one\", 2 \"two\", 3 \"three\"}) (= (__ [:foo :bar] [\"foo\" \"bar\" \"baz\"]) {:foo \"foo\", :bar \"bar\"})</p> <p>;; If we could use zipmap then the answer would be simple</p> <p>(zipmap [:a :b :c] [1 2 3]) ;; =&gt; {:a 1, :b 2, :c 3}</p> <p>(= (zipmap [:a :b :c] [1 2 3]) {:a 1, :b 2, :c 3}) ;; =&gt; true</p> <p>;; So now we have to figure out the algorithm that zipmap uses</p> <p>;; Analyse the problem ;; We want to create a paring of values from the first and second vectors ;; Then each pair should be made into a key value pair within a map data structure.</p> <p>;; The map function will work over multiple collections, returning a single collection</p> <p>;; A simple example of map function in action: (map str [:a :b :c] [1 2 3]) ;; =&gt; (\":a1\" \":b2\" \":c3\")</p> <p>;; In stead of string, we could use hash-map</p> <p>(map hash-map [:a :b :c] [1 2 3]) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>;; now we just need to put all the maps into one map, so perhaps merge will work</p> <p>(merge (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>(conj (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; ({:a 1} {:b 2} {:c 3})</p> <p>(reduce conj (map hash-map [:a :b :c] [1 2 3])) ;; =&gt; {:c 3, :b 2, :a 1}</p> <p>;; (reduce conj (map vectork ks vs))</p> <p>((fn [key-sequence value-sequence]    (into {}          (map vector key-sequence value-sequence)))  [:a :b :c] [1 2 3]) ;; =&gt; {:a 1, :b 2, :c 3}</p>"},{"location":"data-structures/hash-maps/update/","title":"Update Hash-maps","text":""},{"location":"defining-behaviour-with-functions/","title":"Defining behaviours with functions","text":"<p>Clojure has functions, rather than methods for defining behaviour / \"algorithms\"</p> <p>Clojure design at its most basic comprises:</p> <ul> <li>one or more data structures</li> <li>functions that process those data-structures</li> </ul> <p>There is a common saying in Clojure: \"Its better to have one data structure and many functions, than many data structures and many functions\"</p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/","title":"Anonymous Functions","text":"<p><code>clojure.core/fn</code> is a function for defining custom functions.</p> <p><code>fn</code> is called the anonymous function as it has no external name by which it can be referred by. They are used within the scope of another function call, as having no name they cannot be called from another part of the code.</p> <pre><code>(map (fn [args] ,,,) [1 2 3])\n((fn [args] ,,,))\n</code></pre> <p>The value of using anonymous functions comes when there is a short, specific piece of behaviour required which is unlikely to be needed elsewhere in the code.  An anonymous function can always be refactored into a <code>defn</code> expression if used in multiple places.</p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#definition-of-an-anonymous-function","title":"Definition of an anonymous function","text":"<pre><code>(fn [argument] (str \"some behaviour, typically using the arguments passed:\" argument ))\n</code></pre> <p>This expression is a function call to <code>fn</code> which has the arguments called <code>argument</code></p>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#calling-an-anonymous-function","title":"Calling an anonymous function","text":"<p>To get a value from evaluating this function you need to pass it a value (or another function) as an argument,  as well as calling it as a function by placing the anonymous function as the first element of a list.</p> <pre><code>((fn [arguments] (str \"behaviour, typically using the arguments passed: \" arguments )) \"Is this the right room for an argument\")\n</code></pre>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#binding-a-local-names","title":"Binding a local names","text":"<p><code>fn</code> can have a local name which can be used to write a recursive function (a fn that calls itself).</p> <p>Adding a name also helps with debugging code, as the name will be used to identify that function call if it appears in a stack trace of an exception.</p> <p>A recursive function that counts the elements in a collection</p> <pre><code>(fn -count [xs]\n  (if (empty? xs)\n    0\n    (inc (-count (rest xs)))))\n</code></pre> <pre><code>(fn meaningful-name\n  []\n  (str \"If I fail, you will know my name\"))\n</code></pre>"},{"location":"defining-behaviour-with-functions/anonymous-functions/#anonymous-function-syntactic-sugar","title":"Anonymous function Syntactic Sugar","text":"<p>There is a short form of the function definition using the <code>#( ,,, )</code> syntax.</p> <p>For example, if we want to increment an argument we could start to define an anonymous function as follows:</p> <pre><code>#(inc %)\n</code></pre> <p>The <code>%</code> represents a placeholder for an argument that is passed into the anonymous function.  This argument is anonymous as well as the value is simply swapped into the position of <code>%</code>.</p> <p>To evaluate this anonymous function we need to give it an argument to work on.  Anything after the anonymous function is taken as its argument.  So in the following expression we pass the value 1 as the argument and we should get the result of incrementing 1 as a result</p> <pre><code>( #(inc %) 1 )\n\n;; =&gt; 2\n</code></pre> <p>The <code>%</code> placeholder can also refer to a specific argument by adding an index number.  The index numbers refer to the position of the arguments supplied to the anonymous function.</p> <p>Here we will add two different arguments together</p> <pre><code>( #(+ %1 %2) 20 22)\n</code></pre> <p>So <code>%1</code> will represent the first argument and the <code>%2</code> will represent the second argument passed to this function.</p> <p>Sometimes position can be important as the following two versions of code demonstrate</p> <pre><code>( #(/ %1 %2) 24 6)\n\n( #(/ %2 %1) 24 6)\n</code></pre> <p>These two expressions give different values (and return different types, Integer and Ratio) as the positions of the arguments have been reversed.</p>"},{"location":"defining-behaviour-with-functions/calling-functions/","title":"Calling Functions","text":"<p>To call a function in Clojure you use the name of the function as the first element of a list.</p> <p>In this simple example, a function is defined that takes no arguments, then that function is called.</p> <pre><code>(defn my-function []\n  (str \"I only return this string\"))\n\n(my-function)\n</code></pre> <p>Functions can be defined to take arguments.</p>"},{"location":"defining-behaviour-with-functions/calling-functions/#arity","title":"Arity","text":"<p>This is the term to describe the number of arguments a function takes.  This can be a fixed number or variable number of arguments.</p> <p>Simple polymorphism can also be used to have one function take different numbers of arguments, as with the <code>multi-arity</code> function in the examples below.</p> <pre><code>(defn single-arity [] \n  (str \"I do not take any arguments\"))\n\n(defn single-arity [argument] \n  (str \"I take 1 argument only\"))\n\n(defn triple-arity [argument1 argument2 argument3] \n  (str \"I take 3 arguments only\"))\n\n(defn multi-arity \n ([argument] \n   (str \"I match 1 argument only\"))\n ([argument1 argument2]\n   (str \"I match when 2 arguments are used\")))\n\n(defn variable-arity [argument &amp; more-arguments]\n  (str \"I assign the first argument to argument, \n        all other arguments to more-arguments\"))\n</code></pre>"},{"location":"defining-behaviour-with-functions/examples/","title":"Examples","text":""},{"location":"defining-behaviour-with-functions/parameters/","title":"Parameters","text":""},{"location":"defining-behaviour-with-functions/syntax/","title":"Syntax","text":"<p>Defining functions is done with the <code>fn</code> function</p> <p>We have already seen the <code>def</code> function to assign names to values.  We can also use the same function to give a name to our functions.</p>"},{"location":"designing-data-structures/","title":"Designing Data Structures","text":"<p>Some common design guides for data structures in Clojure</p>"},{"location":"designing-data-structures/#the-basics-design-approach","title":"The Basics design approach","text":"<p>Most data structures in Clojure seem to be created from either vectors or maps or a combination of both.  Sets are used where uniqueness of values is important and lists are often used for their lazy properties.</p> <p>Vectors are the most flexible data structure in Clojure and support none-sequential access as they are indexed.</p> <p>Maps are really useful for defining semantic meaning to your data structures, helping you create data structures that express the context of the model they represent.  Maps give you unordered, arbitrary index arrangement. Access is iteration of key/value pairs or getting a value for a given key.</p> <p>Lists give you sequential, one-at-a-time arrangement. They allow for efficient iteration, lazy generation, and stack discipline.</p> <p>Sets give you unordered, unique constraint arrangement. Access is iteration of elements or checking containment.</p>"},{"location":"designing-data-structures/modeling-alphabet-codes/","title":"Model alphabet codes","text":"<p>Maps in Clojure are used to model key and value pairs.</p> <ul> <li>Keys must be unique within a map.</li> <li>A key can be a number, string or keyword.</li> </ul> <p>Vectors in Clojure are a general data structure that are good for handing any kind of information.</p> <p>Note Define a data structure where each letter of the alphabet is represented by a 6 digit binary code</p> <p>Lets define a name called <code>alphabet</code> that is bound to a map.  Each key in the map is a character of the alphabet and each value is a vector of numbers that represent a binary code.</p> <p>The map also includes a binary code for a full stop and space character</p> <pre><code>(def alphabet {\"A\" [0 1 0 0 0 1]\n               \"B\" [0 0 1 0 1 0]\n               \"C\" [0 1 0 0 1 0]\n               \"D\" [1 0 1 0 0 0]\n               \"E\" [1 0 1 1 0 0]\n               \"F\" [1 1 0 1 0 0]\n               \"G\" [1 0 0 1 1 0]\n               \"H\" [1 0 1 0 0 1]\n               \"I\" [1 1 1 0 0 0]\n               \"J\" [0 0 1 1 1 1]\n               \"K\" [0 1 0 1 0 1]\n               \"L\" [1 1 1 0 0 1]\n               \"M\" [1 1 1 0 1 1]\n               \"N\" [0 1 1 1 0 1]\n               \"O\" [1 1 0 1 1 0]\n               \"P\" [1 1 1 1 1 0]\n               \"Q\" [1 0 1 1 1 0]\n               \"R\" [1 1 1 1 0 0]\n               \"S\" [0 1 1 1 1 0]\n               \"T\" [1 0 0 1 1 1]\n               \"U\" [0 0 1 0 1 1]\n               \"V\" [0 1 1 0 0 1]\n               \"W\" [1 1 0 1 0 1]\n               \"X\" [1 0 1 0 1 0]\n               \"Y\" [1 0 0 0 1 1]\n               \"Z\" [1 1 0 0 1 1]\n               \".\" [1 0 1 1 0 1]\n               \" \" [0 0 1 0 0 0]})\n</code></pre>"},{"location":"designing-data-structures/modeling-name-generation-map/","title":"Design a map for name generation","text":"<p>Imagine you are writing a simple name generator that takes your name and creates an alternative version.  For example this could be a generator of your \"Posh\" or \"Hipster\" name.</p> <p>Note Define a data structure to model sloane names that has three names for every letter of the alphabet.  For name suggestions, see the Tattler sloane name generator.</p> <p>The following seems to be the simplest way to model the sloane names.  This follows the representation in the original source material.</p> <pre><code>(def sloane-first-name\n  {\"a\" \"Ally-Pally\"\n   \"b\" \"Bongo\"\n   \"c\" \"Chipper\"})\n\n(def slone-second-name\n  {\"a\" \"Anstruther\"\n   \"b\" \"Beaufort\"\n   \"c\" \"Cholmondeley\"})\n\n(def slone-third-name\n  {\"a\" \"Arbuthnot\"\n   \"b\" \"Battenburg\"\n   \"c\" \"Coutts\"})\n</code></pre> <p>The following alternative data structure design is very simple and more concise, however it does loose some of the semantic meaning.  The position of the names is not defined in terms of the context of the problem.</p> <pre><code>(def slone-names\n  {:a [\"Ally-Pally\" \"Anstruther\" \"Arbuthnot\"]})\n</code></pre> <p>This next design removes some of the redundancy in defining each letter of the alphabet several times.  Apart from less typing and therefore reading by the development team, it also explicitly defines the semantic meaning of each name within the context of this problem.</p> <pre><code>(def slone-names\n  {:a {:first \"Ally-Pally\" :second \"Anstruther\" :third \"Arbuthnot\"}})\n</code></pre> <p>For extra points you could try and implement a function that generated your sloane name.</p>"},{"location":"designing-data-structures/modeling-name-generation-map/#creating-the-algorithm-to-construct-your-sloane-name","title":"Creating the algorithm to construct your sloane name","text":"<ul> <li>The first sloane name is chosen from the first character of the first name</li> <li>The second sloane name chosen from the first character of the second name</li> <li>The third sloane name is chosen from the second character of the second name</li> </ul> <p>You can get the first element of a string by treating it just like a collection.  However this returns a character</p> <pre><code>(first \"Strings also act as collections\")\n</code></pre> <p>A string can be converted to a keyword, a character cannot</p> <pre><code>(keyword \"a\")\n</code></pre> <p>A character can be converted to a string using the str function</p> <pre><code>(str (first \"Strings also act as collections\"))\n</code></pre> <p>The keywords need to be the same case, so convert the first character to lower case (which returns a string, so the explicit str function is no longer required.)</p> <pre><code>(clojure.string/lower-case (first \"Strings also act as collections\"))\n</code></pre> <p>Putting it all together.</p> <pre><code>(keyword (clojure.string/lower-case (first \"Strings also act as collections\")))\n</code></pre>"},{"location":"designing-data-structures/modeling-name-generation-map/#create-a-function-to-calculate-your-sloane-name","title":"Create a function to calculate your sloane name","text":"<p>Putting all this together in a function to generate your sloan name, given your a string with your first and last name.</p> <pre><code>(defn sloane-name\n  \"Given a first and last name as a string, returns your equivalent Sloane name as a string\"\n  [name]\n  (let [first-name  (keyword (clojure.string/lower-case (first (first (clojure.string/split name #\" \")))))\n        middle-name (keyword (clojure.string/lower-case (first (second (clojure.string/split name #\" \")))))\n        last-name   (keyword (clojure.string/lower-case (second (second (clojure.string/split name #\" \")))))]\n    (str (get-in slone-names [first-name  :first])\n         \" \"\n         (get-in slone-names [middle-name :second])\n         \" \"\n         (get-in slone-names [last-name   :third]))))\n</code></pre> <p>Supply a name that will test if the <code>sloane-name</code> function works</p> <pre><code>(sloane-name \"Billy Abstainer\")\n;; =&gt; \"Bongo Anstruther Battenburg\"\n</code></pre>"},{"location":"designing-data-structures/with-maps-of-maps/","title":"With Maps of Maps","text":"<p>Note Define a collection of star-wars characters using a map of maps.  Each character should have an name that they are typically referred to, along with their fullname and skill</p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Crank phone calls\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"}})\n</code></pre> <p>Now we can refer to the characters using keywords.  Using the get function we return all the information about Luke</p> <pre><code>(get star-wars-characters :luke)\n</code></pre> <p>By wrapping the get function around our first, we can get a specific piece of information about Luke</p> <pre><code>(get (get star-wars-characters :luke) :fullname)\n</code></pre> <p>There is also the get-in function that makes the syntax a little easier to read</p> <pre><code>(get-in star-wars-characters [:luke :fullname])\n(get-in star-wars-characters [:vader :fullname])\n</code></pre> <p>Or you can get really concise by just talking to the map directly</p> <pre><code>(star-wars-characters :luke)\n(:fullname (:luke star-wars-characters))\n(:skill (:luke star-wars-characters))\n\n(star-wars-characters :vader)\n(:skill (:vader star-wars-characters))\n(:fullname (:vader star-wars-characters))\n</code></pre> <p>And finally we can also use the threading macro to minimise our code further</p> <pre><code>(-&gt; star-wars-characters\n    :luke)\n\n(-&gt; star-wars-characters\n    :luke\n    :fullname)\n\n(-&gt; star-wars-characters\n    :luke\n    :skill)\n</code></pre> <p>Note* Create a slightly  data structure holding data around several developer events.  Each event should have a website address, event type, number of attendees, call for papers.</p> <pre><code>(def dev-event-details\n  {:devoxxuk     {:URL                 \"http://jaxlondon.co.uk\"\n                  :event-type          \"Conference\"\n                  :number-of-attendees 700\n                  :call-for-papers     \"open\"}\n   :hackthetower {:URL                 \"http://hackthetower.co.uk\"\n                  :event-type          \"hackday\"\n                  :number-of-attendees 99\n                  :call-for-papers     \"closed\"}})\n</code></pre> <p>This data structure is just a map, with each key being the unique name of the developer event.</p> <p>The details of each event (the value to go with the event name key) is itself a map as there are several pieces of data associated with each event name. So we have a map where each value is itself a map.</p> <p>Call the data structure and see what it evaluates too, it should not be a surprise</p> <pre><code>dev-event-details\n</code></pre> <p>We can ask for the value of a specific key, and just that value is returned</p> <pre><code>(dev-event-details :devoxxuk)\n</code></pre> <p>In our example, the value returned from the :devoxxuk key is also a map, so we can ask for a specific part of that map value by again using its key</p> <pre><code>(:URL (dev-event-details :devoxxuk))\n</code></pre>"},{"location":"designing-data-structures/with-maps/","title":"With Maps","text":"<p>Maps allow you to model data with its contextual meaning.  The keys of a map can give the context and the values are the specific data.</p> <p>Note Define a shopping list of items you want, including how many of each item you want to buy</p> <pre><code>(def shopping-list\n  {\"cat food\"  10\n   \"soya milk\" 4\n   \"bread\"     1\n   \"cheese\"    2})\n</code></pre> <p>Note Define a star-wars characters, eg. luke skywalker, jarjar binks.  The star-wars character should include a name and a skill (it doesn't matter what these are).</p> <p>Use the 'get' function to return the value of a given key, eg. name.  Use keywords to return a given value if you used keywords for the map keys.</p> <p>In this answer we have defined three different star-wars characters, all using the same map keys.</p> <pre><code>(def luke   {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"})\n(def darth  {:name \"Darth Vader\"    :skill \"Crank phone calls\"})\n(def jarjar {:name \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"})\n</code></pre> <p>Lets see what the specific skill luke has</p> <pre><code>(get luke :skill)\n</code></pre> <p>When you use a keyword, eg. :name, as the key in a map, then that keyword can be used as a function call on the map to return its associated value.  Maps can also act as functions too.</p> <pre><code>(:name luke)\n(luke :name)\n</code></pre> <p>There are also specific functions that work on maps that give all the <code>keys</code> of a map and all the <code>values</code> of that map</p> <pre><code>(keys luke)\n(vals luke)\n</code></pre>"},{"location":"designing-data-structures/with-vectors-of-maps/","title":"A Vector of Maps","text":"<p>Vectors are good for holding any information whether that be simple values or other collections.</p> <p>Maps are good for defining data with semantic meaning, using the keys to express the context of the values.</p> <p>*Note Define a simple data structure for a collection of stocks in a portfolio.  This would contain a collection of stock information, with each stock holding the ticker name, last trading monetary value and opening monetary value.</p> <p>This is a vector of maps, as there will be one or more company stocks to track.  Each map represents the stock information for a company.</p> <pre><code>(def portfolio [ { :ticker \"CRM\"  :lastTrade 233.12 :open 230.66}\n                 { :ticker \"AAPL\" :lastTrade 203.25 :open 204.50}\n                 { :ticker \"MSFT\" :lastTrade 29.12  :open 29.08 }\n                 { :ticker \"ORCL\" :lastTrade 21.90  :open 21.83 }])\n</code></pre> <p>We can get the value of the whole data structure by referring to it by name</p> <pre><code>portfolio\n</code></pre> <p>As the data structure is a vector (ie. array like) then we can ask for a specific element by its position in the array using the <code>nth</code> function</p> <p>Lets get the map that is the first element (again as a vector has array-like properties, the first element is referenced by zero)</p> <pre><code>(nth portfolio 0)\n</code></pre> <p>The vector has 4 elements, so we can access the last element by referencing the vector using 3</p> <pre><code>(nth portfolio 3)\n</code></pre> <p>As portfolio is a collection, also known as a sequence, then we can use a number of functions that provide common ways of getting data from a data structure</p> <pre><code>(first portfolio)\n(rest portfolio)\n(last portfolio)\n</code></pre> <p>We can get specific information about the share in our portfolio, or as the keys in each map are defined with Clojure keywords, we can also use the keywords to return the specific values they pair with.</p> <pre><code>(get (second portfolio) :ticker)\n;; =&gt; \"AAPL\"\n\n(:ticker (first portfolio))\n;; =&gt; \"CRM\"\n</code></pre> <p>If we want to get specific share information across the whole portfolio, then we can simply <code>map</code> the <code>:ticker</code> keyword over each share in portfolio</p> <pre><code>(map :ticker portfolio)\n;; =&gt; (\"CRM\" \"AAPL\" \"MSFT\" \"ORCL\")\n\n(mapv :ticker portfolio)\n;; =&gt; [\"CRM\" \"AAPL\" \"MSFT\" \"ORCL\"]\n</code></pre>"},{"location":"designing-data-structures/with-vectors-of-vectors/","title":"With Vectors of Vectors","text":"<p>The most frequent use of  you will see is in the <code>project.clj</code> file, where a vector of vectors is used to model the library dependencies for a project</p> <pre><code>[[org.clojure/clojure \"1.8.0\"]\n [org.clojure/core.match \"0.3.0-alpha4\"]]\n\n[[org.clojure/clojure \"1.6.0\"]\n [ring \"1.4.0-beta2\"]\n [compojure \"1.3.4\"]\n [hiccup \"1.0.5\"]]\n</code></pre> <p>Fixme Think of an exercise to create a vector of vectors as a data model</p>"},{"location":"designing-data-structures/with-vectors/","title":"With Vectors","text":"<p>Vectors as the simplest data structure in Clojure to work with.  They are very similar to an array in other languages, although they have additional qualities in Clojure.</p> <p>Vectors</p> <ul> <li>can be of any length</li> <li>are indexed so have fast random access</li> <li>can contain any types</li> <li>are immutable</li> </ul> <p>Define a data structure for a simple shopping list with any items you would typically want to buy.</p> <pre><code>(def shopping-list [\"Cerial\" \"Baked Beans\" \"Cat food\" \"Quorn chicken pieces\" ])\n</code></pre>"},{"location":"development-environments/","title":"Development Environments","text":"<p>This workshop encourages LightTable &amp; Leiningen as the development environment, as they are the easiest tools to set up.</p> <p>Leiningen is the build automation tool used to manage Clojure projects.  It will create projects from templates and run our Clojure environment (REPL).</p> <p>LightTable is a Clojure aware editor that supports the dynamic workflow of Clojure development in a REPL.  LightTable is also written in Clojure (and ClojureScript).</p> <p>The following pages will show you how to set up LightTable and Leiningen.</p>"},{"location":"development-environments/java/","title":"Java","text":""},{"location":"development-environments/java/#java-a-host-platform-for-clojure","title":"Java - a host platform for Clojure","text":"<p>You will need to have a Java Runtime Edition (usually installed on most computers by default) to run any Clojure applications.  Version 8 is recommended (although version 6 &amp; 7 should work).</p> <p>To test if you have Java on your computer, open a command line window and run the command</p> <pre><code>java -version\n</code></pre>"},{"location":"development-environments/java/#installing-the-java-runtime-edition","title":"Installing the Java Runtime Edition","text":"<p>Download and install the latest Oracle Java SDK (version 1.8 at time of writing).</p> <p>Alternatively, install OpenJDK or Zulu build of OpenJDK</p>"},{"location":"development-environments/java/#ubuntu","title":"Ubuntu","text":"<p>The OpenJDK is available as a package on Ubuntu and can be installed via the Ubuntu software center or via the command line:</p> <pre><code>sudo apt-get install openjdk-8-jre\n</code></pre>"},{"location":"development-environments/java/#why-is-java-required","title":"Why is Java Required","text":"<p>Clojure was designed as a hosted language, which means it is developed and run on top of Java's Virtual Machine (JVM).  However, its not necessary to learn the Java language to use Clojure.</p> <p>Clojure is compiled into Java bytecode when you evaluate the code.  This compilation happens in the background so you dont usually see it happening.  For example, if you are using the Clojure REPL then each time you evaluate an expression it is compiled into Java bytecode and then injected into the running REPL and the results are then returned.  This all happens pretty instantaneously.</p> <p>Most of the current Clojure tooling was developed for Clojure on the JVM, for example Leiningen.</p> <p>As Clojure runs on Java you can also use all the other libraries that run on the Java Virtual machine, regardless of whether those libraries were written in Java, Clojure, Scala, JRuby, jython, Groovy, etc.</p>"},{"location":"development-environments/leiningen/","title":"Leiningen Build tool","text":"<p>leiningen.org (pronounced line-ing-en) is a very powerful build automation tool for automating Clojure projects.  With Leiningen you can:</p> <ul> <li>Create Clojure Projects with templates</li> <li>Define and manage dependencies</li> <li>Run an interactive Clojure environment (REPL)</li> <li>Run unit tests using Clojure.test</li> <li>Run your Clojure application</li> <li>Create a deployable Clojure application, as Java Jar file</li> <li>Deploy a Clojure library to a remote repository</li> </ul> <p></p>"},{"location":"development-environments/leiningen/#install-leiningen","title":"Install Leiningen","text":"<p>Download the install script from leiningen.org and run the Leiningen script in a terminal</p> <p>On Linux and MacOSX, make the script executable first</p> <pre><code>chmod a+x lein\n./lein\n</code></pre> <p>Hint I put the <code>lein</code> script in <code>~/bin</code> directory which is part of my operating system execution path ($PATH).  To include the <code>~/bin</code> directory in the system path, I add the following code to the <code>~/.profile</code> file</p>"},{"location":"development-environments/leiningen/#testing-leiningen-is-working","title":"Testing Leiningen is working","text":"<p>Test that Leiningen is installed with the following command</p> <pre><code>lein version\n</code></pre> <p>Output should look similar to:</p> <pre><code>Leiningen 2.6.1 on Java 9-internal OpenJDK 64-Bit Server VM\n</code></pre>"},{"location":"development-environments/lighttable/","title":"LightTable","text":"<p>LightTable is a simple development tool that supports Clojure, ClojureScript, JavaScript and Python languages.  The tool is open source and written in Clojure &amp; ClojureScript (with a little JavaScript &amp; CSS)</p> <p></p>"},{"location":"development-environments/lighttable/#install-lighttable","title":"Install Lighttable","text":"<p>Download lighttable.com and follow the suggested instructions:</p> <p>MacOSX   Install the <code>lighttable.dmg</code> file just as any other MacOSX package</p> <p>Linux   Extract the contents of the downloaded lighttable file to a suitable directory (<code>/usr/local</code> or <code>~/apps</code>).  Add <code>LightTable</code> to the system <code>$PATH</code>, or add the following script to the system <code>$PATH</code>.</p> <p>Windows   Download the windows zip file for LightTable and extract the installer, following the instructions inside the installer.</p>"},{"location":"development-environments/lighttable/#lighttable-configuration","title":"LightTable configuration","text":"<p>Lighttable configuration is in the file <code>user.behaviours</code>.  Open the user behaviours file, <code>Ctrl-space</code> and type <code>user behaviors</code>.  When you save the file, <code>Ctrl-s</code>, changes are applied immediately.</p> <p>Sample User Behaviours file</p> <p>Here is a sample of user behaviours file for LightTable</p>"},{"location":"development-environments/lighttable/#using-lighttable","title":"Using LightTable","text":"<p>LightTable has an online tutorial entitled Getting started with LightTable</p> <p>I create a project first with Leiningen, open the project directory in the LightTable workspace and open any files I want to work with.  I then connect the open editor window for the file by pressing <code>Ctrl-Enter</code> at the end of an expression.</p> <p>Hint my approach is documented in the quick demo section of my Clojure &amp; LightTable slides from JAXLondon 2013.</p>"},{"location":"development-environments/other-tools/","title":"Other Development tools for Clojure","text":"<p>There are several development tools you can use to support your Clojure development.</p> <p>My current choice of development environment is Spacemacs, a feature rich configuration for Emacs.  See my article on Spacemacs for Clojure development</p> <p>Some common setups I have seen in use for Clojure development are:</p> <ul> <li>Modern - LightTable, Leiningen, Git</li> <li>Modern Classic - Spacemacs with Clojure layer, Leiningen, magit</li> <li>Classic - Emacs with Cider, Leiningen, magit</li> <li>Java (IntelliJ) - Cursive Clojure</li> <li>Java (Eclipse) - Counterclockwise documentation site</li> <li>Ubiquitous - Vim, nailgun, Leiningen, Git</li> <li>Simple - Nightcode, Leiningen, Git</li> <li>Lightweight - Atom, Protorepl, Leiningen, Git</li> </ul> <p>There may be many more variations, however you should find a development environment with at minimum the following features:</p> <ul> <li>starting &amp; using a REPL, with in-line evaluation</li> <li>syntax highlighting &amp; coloured brackets (eg. rainbow-delimiters in Emacs)</li> <li>autocomplete of  names (functions, symbols, keywords, etc)</li> <li>snippets / templates</li> </ul>"},{"location":"development-environments/other-tools/#tools-for-developers-with-a-java-background","title":"Tools for developers with a Java background","text":"<p>Clojure runs on the Java Virtual Machine so its not surprising that there is good support for Clojure in the major Java IDEs.</p>"},{"location":"development-environments/other-tools/#eclipse","title":"Eclipse","text":"<p>Counterclockwise is an Eclipse IDE plugin to provide an integrated development environment for Clojure.  Take a look at the Counterclockwise documentation site for installation instructions</p>"},{"location":"development-environments/other-tools/#intellij","title":"IntelliJ","text":"<p>Cursive is a Clojure IDE that aims to understands your code.  Advanced structural editing, refactor, VCS integration and much more, all out of the box.  It is currently a standalone tool, although will eventually become an IntelliJ plugin.</p> <p>La Clojure is a plugin for IntelliJ IDEA.  Provides Clojure language support: syntax and error highlighting, completion, navigation and refactor.</p>"},{"location":"development-environments/other-tools/#netbeans","title":"Netbeans","text":"<p>Netbeans did have great support for Clojure, but unfortunately at the time of writing the Clojure plugin has been unmaintained for so long it is not a viable tool to use for Clojure development.</p>"},{"location":"games/","title":"Writing Games with Clojure","text":"<p>Games are driven by events and require state to be managed, so are a good way to explore how to manage state with immutable values.</p> <p>For games in Clojure the events are simply function calls and we prefer to pass the state around rather than have a central mutable container for our state.</p> <p>This section will contain several games that have been built using a functional approach with immutable data structures.</p> <ul> <li>TicTacToe on the command line</li> </ul>"},{"location":"games/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Pull requests are welcome</p>"},{"location":"games/#hintgames-in-clojurescript","title":"Hint::Games in ClojureScript","text":"<p>There is a section on games in the Practicalli ClojureScript book, including a TicTacToe game using Reagent (react.js style library) and Scalable Vector Graphics (SVG).</p>"},{"location":"games/tictactoe-cli/","title":"TicTacToe on the command line","text":"<p>Tic-tac-toe is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3\u00d73 grid. The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row wins the game</p> <p></p> <p> </p> <p>The code for this section is published on GitHub at: practicalli/tictactoe-cli</p> <p>A TicTacToe game that you run on the command line.  The game takes input from a human player and the program is the second player.</p> <p></p> <p>Output from the game appears in the REPL</p> <pre><code>Current board:\n1 | 2 | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | 2 | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | 3\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\n4 | 5 | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | 5 | 6\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | 6\n---------\n7 | 8 | 9\nO: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | O\n---------\n7 | 8 | 9\nX: Select your move (press a number between 1 and 9 then press enter)\nCurrent board:\nX | O | X\n---------\nO | X | O\n---------\nX | 8 | 9\nPlayer  X  wins!\n</code></pre>"},{"location":"games/tictactoe-cli/#references","title":"References","text":"<ul> <li>TicTacToe game created by Brian Will.</li> </ul>"},{"location":"games/tictactoe-cli/create-project/","title":"Create a Clojure project","text":"<p>Create a project for our game.</p> <p>{% tabs deps=\"deps.edn projects\", lein=\"Leiningnen projects\" %}</p> <p>{% content \"deps\" %} Create a new project using <code>clj-new</code> alias, found in  Practicalli Clojure CLI Config</p> <pre><code>clojure -M:new practicalli/tictactoe-cli\n</code></pre> <p>Open the project in a Clojure aware editor or run a rebel REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre> <p>Once the rebel REPL is running, load the project and change to the main namespace</p> <pre><code>(require 'practicalli/tictactoe-cli)\n\n(in-ns 'practicalli/tictactoe-cli)\n</code></pre> <p>{% content \"lein\" %} The default Leiningen template is suitable fine for the project as no additional libraries are used.</p> <pre><code>lein new tictactoe-cli\n</code></pre> <pre><code>git clone https://github.com/practicalli/tictactoe-cli.git\n</code></pre>"},{"location":"games/tictactoe-cli/create-project/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"games/tictactoe-cli/create-project/#hintalternatively-clone-the-github-repository","title":"Hint::Alternatively clone the github repository","text":"<p>You can also clone the tictactoe-cli game from GitHub</p>"},{"location":"games/tictactoe-cli/create-project/#updating-clojure-version-and-licence","title":"Updating Clojure version and licence","text":"<p>In the <code>project.clj</code> file I have updated Clojure to version 1.10.0 and changed the licence to be the more open Creative Commons license.</p> <pre><code>(defproject tictactoe-cli \"0.1.0-SNAPSHOT\"\n  :description \"TicTacToe game played on the command line\"\n  :url \"https://github.com/practicalli/tictactoe-cli\"\n  :license {:name \"Creative Commons Attribution Share-Alike 4.0 International\"\n            :url \"https://creativecommons.org\"}\n  :dependencies [[org.clojure/clojure \"1.10.0\"]])\n</code></pre> <p>I also removed the <code>license</code> file and added a brief description of the project to the <code>README.md</code> file</p> <p>{% endtabs %}</p>"},{"location":"install/","title":"Install Clojure","text":"<p>Clojure CLI provides the foundation for Clojure development, providing a declarative approach to:</p> <ul> <li>Run Clojure programs and tools</li> <li>Run a REPL process (Read-Eval-Print Loop) and provides a basic interactive terminal UI</li> <li>Manage packaged dependencies from Maven (jars) and use Git repositories as dependencies</li> </ul> <p>Practicalli Clojure Config community tools</p> <p> Practicalli Clojure CLI Config is a user configuration providing aliases for a wide range of community tools which extends the features of Clojure CLI.  The aliases include tools to create, develop, build and deploy Clojure code.  Aliases are used heavily in the Practicalli books.</p> <p>If the Practicalli Clojure CLI config is not used, review the  <code>deps.edn</code> file from the GitHub repository and add relevant aliases definitions to your own Clojure CLI configuration.</p>"},{"location":"install/#pre-requisites","title":"\"Pre-requisites\"","text":"<p>A Java Virtual Machine hosts Clojure. Java 21 is the current Long Term Support version providing a stable platform to run Clojure</p>"},{"location":"install/#additional-tools","title":"Additional tools","text":"<p>Clojure connected editor</p> <p>A Clojure connected editor provides the most effective way to write and maintain Clojure projects.  The editor connects to (or starts) a Clojure REPL and code can be evaluated as its typed, showing the results instantly in line with the code.</p> <p>Clojure LSP server generates static analysis of code which editors can surface as code diagnostics.  Analysis supports effective code navigate and refactor tools.  Practicalli Clojure LSP config configures </p> <p>Data Inspectors</p> <p>Data inspectors visualize results of Clojure code evaluation and allow navigation of nested data or paging through large data sets.</p> <p>Portal is highly recommended data inspector and included in projects generated with Practicalli Project Templates.</p> Alternative development tools <p>Leiningen is the long-standing development tool for Clojure.  All the code examples in this book should work with Leiningen when a correctly configured <code>project.clj</code> file is created which includes all the necessary library dependencies.  Libraries included via aliases should be added as either <code>:dev-dependencies</code> or <code>:aliases</code> in the Leiningen <code>project.clj</code> file.</p>"},{"location":"install/clojure-cli/","title":"Install Clojure CLI","text":"<p>Clojure CLI is a command line tool for running a Clojure REPL, project or tool.</p> <p>Clojure CLI automatically downloads required library dependencies, including the Clojure Standard library. </p> Clojure distributed as a library <p>Clojure is distributed as a library (<code>.jar</code> Java ARchive) via Maven Central. </p> <p>A <code>deps.edn</code> file specifies the version of Clojure to be used with a project.</p> <pre><code>:deps {org.clojure/clojure {:mvn/version \"1.12.0\"}}\n</code></pre> <p>The Clojure CLI tool provides a default Clojure library version if not specified in the project or user <code>deps.edn</code> files.</p> <p>Clojure releases </p> <p> Practicalli Clojure CLI Config extends the Clojure CLI with a range of development tools as well as configuration for Clojure LSP and cljstyle code format tool.</p> LinuxHomebrewWindows <p>Use the Linux script installer from Clojure.org - Getting Started to install or update to the latest stable release</p> <pre><code>curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\nsudo ./linux-install.sh\n</code></pre> <p>The installation creates <code>/usr/local/bin/clojure</code>, <code>/usr/local/bin/clj</code> wrapper and <code>/usr/local/lib/clojure</code> directory.</p> Use alternative location - unattended install <p><code>--prefix</code> option specifies an alternative lolcation for the Clojure CLI install.</p> <p>When permissions are not available or for automating the install without password prompt, use a local user specific install, e.g. <pre><code>curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install.sh &amp;&amp; \\\n./linux-install.sh --prefix $HOME/.local/\n</code></pre></p> Include version number for specific release <p>Each Clojure CLI version is a number that represents the version of Clojure used and the build version of the Clojure CLI tool, e.g. <code>1.11.1.1413</code>.</p> <p>Clojure CLI Releases page </p> <p>Include the version in the script name for repeatable environments, e.g. in Dockerfile configuration and Continuous Integraion workflows. Clojure CLI install specific version<pre><code>curl -L -O https://github.com/clojure/brew-install/releases/1.11.1.1413/download/linux-install.sh &amp;&amp; \\\nchmod +x linux-install-1.11.1.1413.sh\nsudo ./linux-install-1.11.1.1413.sh\n</code></pre></p> <p>Practically recommends setting <code>XDG_CONFIG_HOME</code> to the <code>.config</code> directory, to avoid creating another dot directory in the root of the user account.  Add the following to <code>~/.bashrc</code> for the bash shell or <code>~/.zshenv</code> for Zsh. <pre><code>export XDG_CONFIG_HOME=\"$HOME/.config\"\n</code></pre></p> <p>Use the Homebrew command with the clojure/tools tap, as defined in the Clojure.org Getting started guide</p> <pre><code>brew install clojure/tools/clojure\n</code></pre> <p>Use Homebrew to update an install of Clojure CLI to the latest release <pre><code>brew upgrade clojure/tools/clojure\n</code></pre></p> <p>Homebrew on Linux or Windows with WSL</p> <p>For Windows 10 use Windows Subsystem for Linux and Windows Terminal are recommended if you have administrative privileges and are comfortable using a Unix system on the command line.</p> <p>Alternatively install scoop.sh, a command line installer for windows.  Powershell 5 or greater is required. Follow the scoop-clojure getting started guide, summarized here:</p> <p>Open \"Windows PowerShell\" and enter the following commands to configure the shell:</p> <p><pre><code>iwr -useb get.scoop.sh | iex\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force\n</code></pre> Then in the same PowerShell window, install the Clojure related tools using the following commands:</p> <pre><code>scoop bucket add extras\nscoop bucket add java\nscoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure\nscoop install git 7zip pshazz temurin-lts-jdk clj-deps leiningen clj-kondo vscode coreutils windows-terminal\n</code></pre> <p>Reference: Clojure CLI Install - Clojure.org Getting Started - official guide</p>"},{"location":"install/clojure-cli/#practicalli-clojure-cli-config","title":"Practicalli Clojure CLI Config","text":"<p>Add a wide range of community tools to extend the capabilities of Clojure CLI via the aliases.</p> <p>Clone  Practicalli Clojure CLI Config GitHub repository, first removing the <code>$XDG_CONFIG_HOME/clojure</code> and <code>$HOME/.clojure</code> directory if they exist.</p> User configuration locations <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, then the user configuration is <code>$XDG_CONFIG_HOME/clojure/deps.edn</code></p> <p>Otherwise the user configuration is <code>$HOME/.clojure/deps.edn</code>.</p> <p><code>CLJ_CONFIG</code> environment variable can be used to set a custom location, overriding any other location.</p> <p>Practicalli recommends FreeDesktop XDG location</p> <p>Practically recommends setting <code>XDG_CONFIG_HOME</code> to the <code>.config</code> directory to simplify versioning of configuration. </p> <p>Configure <code>~/.bashrc</code> for the bash shell  Bash .bashrc file<pre><code>export XDG_CONFIG_HOME=\"$HOME/.config\"\n</code></pre></p> <p>Configure <code>~/.zshenv</code> for Zsh <pre><code># Set XDG_CONFIG_HOME for clean management of configuration files\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:=$HOME/.local/share}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:=$HOME/.cache}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n</code></pre></p> Free Desktop XDG CONFIGClassic Config <p>If <code>XDG_CONFIG_HOME</code> environment variable is set, clone the repository to <code>$XDG_CONFIG_HOME/clojure</code></p> <p>Via SSH <pre><code>git clone git@github.com:practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure\n</code></pre></p> <p>Via HTTPS: <pre><code>git clone https://github.com/practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure\n</code></pre></p> <p>Clojure CLI will look for its configuration in <code>$HOME/.clojure</code> directory if <code>$XDG_CONFIG_HOME</code> and <code>CLJ_CONFIG</code> environment variables not set. Via SSH ```shell git clone git@github.com:practicalli/clojure-cli-config.git $HOME/.clojure</p> <p>```</p> <pre><code>Via HTTPS\n```shell\ngit clone https://github.com/practicalli/clojure-cli-config.git $HOME/.clojure\n```\n</code></pre>"},{"location":"install/clojure-cli/#check-configuration","title":"Check Configuration","text":"<p><code>clojure -Sdescribe</code> shows the version of Clojure CLI installed and configuration locations used.</p> <pre><code>clojure -Sdescribe\n</code></pre> <p>The output of the command includes the version of Clojure CLI in the <code>:version</code> key</p> <pre><code>{:version \"1.11.1.1386\"\n :config-files [\"/usr/local/lib/clojure/deps.edn\" \"/home/practicalli/.config/clojure/deps.edn\" ]\n :config-user \"/home/practicalli/.config/clojure/deps.edn\"\n :config-project \"deps.edn\"\n :install-dir \"/usr/local/lib/clojure\"\n :config-dir \"/home/practicalli/.config/clojure\"\n :cache-dir \"/home/practicalli/.cache/clojure\"\n :force false\n :repro false\n :main-aliases \"\"\n :repl-aliases \"\"}\n</code></pre> <p><code>clojure -Sversion</code> will shows the version of Clojure CLI being when the <code>clojure</code> command is used to run a REPL or other Clojure command.</p>"},{"location":"install/clojure-cli/#optional-rlwrap-readline","title":"Optional rlwrap readline","text":"<p>The <code>rlwrap</code> binary is a basic readline tool that provides a history of commands entered into a terminal UI when running a Clojure REPL with the <code>clj</code> wrapper script.</p> <p>Pressing the Up and Down keys will scroll through the code previously entered in the REPL.</p> <p><code>rlwrap</code> is available with most Linux systems. Look for  install instructions by searching for rlwrap in a web browser or build from source from the  rlwrap GitHub repository.</p> <p>Use Rebel Readline for a rich terminal UI experience</p> <p> rebel readline is an advanced readline tool providing auto-completion, documentation, signature help and multi-line editing, all within a terminal UI</p> <p>Rebel is a much richer experience than the <code>clj</code> wrapper with <code>rlwrap</code>.  Rebel should not be used with <code>clj</code>.</p> <p>Rebel Readline is part of the Practicalli Clojure CLI config.</p>"},{"location":"install/java/","title":"Java Host","text":"<p>Java is a host platform for Clojure, on which Clojure projects and tools run.  Java provides a virtual machine which runs the bytecode generated when Clojure code is compiled.</p> <p>Java virtual machine includes a Just In Time (JIT) compiler that optimises running of bytecode.</p> <p>Practicalli recommends OpenJDK version 21</p>"},{"location":"install/java/#install-java","title":"Install Java","text":"<p>Check to see if there is an appropriate version of Java already installed.</p> <p>Open a terminal and run the command</p> <pre><code>java --version\n</code></pre> <p>If Java is installed and on the execution path, the version infomation is returned</p> <p> </p> Debian PackagesHomebrewWindowsManual <p>Install Java development kit (JDK) using the <code>apt</code> package manager (login as <code>su -</code> or prefix the command with <code>sudo</code>)</p> <pre><code>apt install openjdk-21-jdk\n</code></pre> Check available versions of OpenJDK <p>Long terms support versions should include OpenJDK 17 and may include OpenJDK 21.  Check versions available via the <code>apt</code> package management tool.</p> <pre><code>apt search --names-only openjdk\n</code></pre> Optionally include Java docs and sources <p>Install the <code>openjdk-21-doc</code> locally to provide Javadocs to support Java Interop code.</p> <p>Install the <code>openjdk-21-source</code> package to support navigation of Java Object and Method source code, especially useful when using Java Interoperability from within Clojure code.</p> <pre><code>sudo apt install openjdk-21-doc openjdk-21-source\n</code></pre> <p> Practicalli Clojure CLI Config provides the <code>:src/java17</code> alias to include the Java sources in the classpath when running a REPL.</p> <p>If <code>openjdk-21-jdk</code> package is not available, add the Ubuntu OpenJDK personal package archive</p> <pre><code>sudo add-apt-repository ppa:openjdk-r/ppa\nsudo apt-get update\n</code></pre> <p>When multiple versions of Java are installed, set the version using the <code>update-alternatives</code> command in a terminal</p> <pre><code>sudo update-alternatives --config java\n</code></pre> <p>Available java versions will be listed.  Enter the list number for the version you wish to use.</p> <p>Using Homebrew, run the following command in a terminal to install Java 17:</p> <pre><code>brew install openjdk@21\n</code></pre> Switching between Java versions <p>More than one version of Java can be installed on MacOSX. Set the Java version by opening a terminal and using one of the following commands</p> <p>Show the Java versions installed <pre><code>/usr/libexec/java_home -V\n</code></pre></p> <p>Switch to Java version 21 <pre><code>export JAVA_HOME=$(/usr/libexec/java_home -v 21)\n</code></pre></p> <p>Alternatively, install JEnv Java version manager</p> <p>For Windows 10 use Windows Subsystem for Linux and Windows Terminal are recommended if you have administrative privileges and are happy to use a Unix system on the command line.</p> <p>Alternatively use scoop.sh, a command line installer for windows.  Powershell 5 or greater is required.</p> <p>Follow the scoop-clojure install instructions, summarized here:</p> <pre><code>scoop bucket add java\nscoop install temurin-lts-jdk\n</code></pre> <p>scoop can also be used to install clojure</p> <p>If neither Scoop or Windows Subsystem for Linux work, try the Chocolatey package manager. Install the Java Runtime (JRE) using the following command in a command line window</p> <pre><code>choco install javaruntime\n</code></pre> <p>If Chocolatey does not work, then try the manual Java install.</p> <p>Download OpenJDK from Adoptium - pre-build OpenJDK binaries freely available for multiple operating systems.</p> <p>Run the file once downloaded and follow the install instructions.</p> <p></p>"},{"location":"install/java/#multiple-versions-of-java","title":"Multiple versions of Java","text":"<p> jenv provides a simple way to switch between multiple installed versions of Java.  jenv can be used to set the java version globally, for the current shell or for a specific project by adding <code>.java-version</code> file containing the Java version number in the root of the project.</p>"},{"location":"install/java/#a-little-java-knowledge","title":"A little Java Knowledge","text":"<p>Very little knowledge of the Java language or the Java Virtual Machine is required.</p> <p>It is quite simple to call Java methods from Clojure, although there are a wealth of functions and libraries provided by Clojure and its community to minimise the need for Java Interoperability.</p> <p>Reading stack traces may benefit from some Java experience, although its usually the first couple of lines in a stack trace that describe the issue.</p> <p>Clojure uses its own build tools (Leiningen, Clojure CLI tools) and so Java build tool knowledge is not required.</p> <p>When libraries are added to a project, they are downloaded to the <code>$HOME/.m2</code> directory.  This is the default Maven cache used by all JVM libraries.</p> <p><code>clojure  -Spom</code> will generate a Maven pom.xml file used for deployment. Understanding of a minimal Maven POM (pom.xml) file is useful when managing issues with packaging and deployment.</p> <p>Maven in 5 minutes</p> <p>The Java Virtual Machine is highly optimised and does not usually require any options to enhance its performance. The most likely configuration to supply to the JVM are to manage the amount of memory assigned, specifically for resource constrained environments.</p>"},{"location":"introduction/clojure-in-15-minutes/","title":"Clojure in 15 minutes","text":"<p>A quick tour of the Clojure syntax and common functions, which is so terse you can read through this page in around 15 minutes and have a basic understanding of the language.</p> <p>Try the code out in the REPL</p> <p> Start a Clojure REPL or use a  Clojure aware editor connected to a REPL and experiment with these code examples.</p> <p>Using the REPL provides instant feedback on each expression as they are evaluated, greatly increasing your understanding.</p>"},{"location":"introduction/clojure-in-15-minutes/#comments","title":"Comments","text":"<p><code>;;</code> two semi-colons for a line comment, <code>;</code> single semi-colon to comment the rest of the line</p> <p><code>#_</code> comment reader macro to comment out the next form</p> <p><code>(comment ,,,)</code> form to comment all the containing forms, useful to  separate experimental and established code in a namespace.</p>"},{"location":"introduction/clojure-in-15-minutes/#clojure-expressions","title":"Clojure expressions","text":"<p>Clojure is mostly written with \"expressions\", a lists of elements inside parentheses, <code>()</code>, separated by space characters.</p> <p>Clojure evaluates the first element in an expression as a function call.  Additional elements in the expression are passed as value arguments to the called function.</p> <p>Function call with value and expression as arguments</p> <pre><code>(+ 2007 (* 1 16))\n</code></pre> <p>Functions can be passed as an argument</p> <pre><code>(map inc (range 0 99))\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#organising-clojure","title":"Organising Clojure","text":"<p>Clojure code is organised into one or more namespaces. The namespace represents the directory path and file name that contains the code of the particular namespace.</p> <p>A company name or community repository name is often used making the namespace unique and easier to share &amp; reuse.</p> ns form returns nil value <p>The <code>(ns namespace.,,,)</code> expression returns a <code>nil</code> value, as its work is done behind the scenes.</p> <p>All Clojure functions must return a value and <code>nil</code> is a value that means 'no value'.</p> <p>Define a namespace</p> src/practicalli/game_board.clj<pre><code>(ns practicalli.game-board)\n</code></pre> <p>Define a longer namespace</p> src/com/company/product/component_name.clj<pre><code>(ns com.company.product.component-name)\n</code></pre> Namespaces use dash, directory and file names use underscore <p>Clojure uses <code>kebab-case</code> for names (common in Lisp dialects)</p> <p>Unfortunately the Java Virtual Machine that hosts Clojure does not support dash, <code>-</code>, in file and directory names, so an underscore, <code>-</code>, character is used</p>"},{"location":"introduction/clojure-in-15-minutes/#string-manipulation","title":"String manipulation","text":"<p>The <code>str</code> function creates a new string from all the arguments passed</p> <p>Combine strings into a single string value</p> <pre><code>(str \"Hello\" \" \" \"World\")\n</code></pre> <p><code>\"Hello World\"</code> is returned from evaluating the expression.</p> <p>clojure.string library for manipulating strings</p> <p><code>clojure.string</code> library functions manipulate values and return string values (other clojure.core functions my return characters as results, e.g. <code>map</code>)</p>"},{"location":"introduction/clojure-in-15-minutes/#math-truth-prefix-notation","title":"Math, Truth &amp; prefix notation","text":"<p>Functions use prefix notation, so you can do math with multiple values very easily</p> <p>Prefix syntax takes multiple arguments</p> <pre><code>(+ 1 2 3 5 7 9 12) ; =&gt; 40\n</code></pre> <p>Math in Clojure is very precise, no need for operator precedence rules (as there are no operators)</p> <p>Nesting forms defined a very precise calculation</p> <p>Parentheses used instead of operator preceedence rules</p> <pre><code>(* 1 2 (- 24 (* 7 3)))\n</code></pre> <p><code>6</code> is returned as the value.  Nested expressions are typically read inside out.  <code>(* 7 3)</code> is <code>21</code>, giving <code>(- 24 21)</code> expression resulting in <code>3</code>.  Finally the expression becomes <code>(* 1 2 3)</code>, resulting in a value of <code>6</code></p> <p>Maintain precision for calculations using a Ratio type in Clojure</p> <p>Clojure Ratio value</p> <pre><code>(/ 27 7)  ; =&gt; 27/7\n</code></pre> <p><code>22/7</code> is returned as the value, rather than a floating point value (double) which may loose some precision due to rounding.</p>"},{"location":"introduction/clojure-in-15-minutes/#equality","title":"Equality","text":"<p><code>=</code> function provides a test for equality</p> <p>Equal values return a boolean true</p> <pre><code>(= 1 1) ; =&gt; true\n</code></pre> <p>Unequals values return a boolean false</p> <pre><code>(= 2 1) ; =&gt; false\n</code></pre> <p><code>true</code> and <code>false</code> are Boolean values and can be used literally in Clojure.</p>"},{"location":"introduction/clojure-in-15-minutes/#predicates","title":"Predicates","text":"<p>A predicate is a function that returns a boolean <code>true</code> or <code>false</code> value and by convention the function name ends in <code>?</code>, e.g. <code>true?</code>, <code>false?</code>, <code>seq?</code>, <code>even?</code>, <code>uuid?</code>.</p> <p><code>and</code> &amp; <code>or</code> functions can be used to chain the results of predicates together for more interesting conditional tests.</p> <p>All predicates are true, returning true</p> <pre><code>(and (true? true) (not false)) ; =&gt; true\n</code></pre> <p>One of the predicates or values is true</p> <pre><code>(or nil (not= true false) (true? (complement true?)) ) ; =&gt; true\n</code></pre> <p>Truthy and Falsy values in Clojure</p> <p><code>false</code> boolean value and <code>nil</code> value are considered false in Clojure.</p> <p>All other values are consider true.</p> <p> Clojure Standard Library Predicate Functions</p>"},{"location":"introduction/clojure-in-15-minutes/#collections-sequences","title":"Collections &amp; Sequences","text":"<p>The most common data collections in Clojure:</p> <ul> <li><code>(1 2 \"three\")</code> or <code>(list 1 2 \"three\")</code> - a list of values read from start to end (sequential access)</li> <li><code>[1 2 \"three\"]</code> or <code>(list 1 2 \"three\")</code> - a vector of values with index (random access)</li> <li><code>{:key \"value\"}</code> or <code>(hash-map :key \"value\")</code> - a hash-map with zero or more key value pairs (associative relation)</li> <li><code>#{1 2 \"three\"}</code> or <code>(set 1 2 \"three\")</code> - a unique set of values</li> </ul> <p>A list <code>()</code> is evaluated as a function call. The first element of the list the name of the function to call and additional values are arguments to the function.</p> <p>The <code>'</code> quote function informs the Clojure reader to treat the list as data only.</p> <p>A quoted list is treated as data</p> <pre><code>'(1 2 3) ; =&gt; (1 2 3)\n</code></pre> <p>Lists and vectors are collections</p> <pre><code>(and (coll? '(1 2 3)) (coll? [1 2 3])) ; =&gt; true\n</code></pre> <p>Only lists are sequences</p> <pre><code>(seq? '(1 2 3)) ; =&gt; true\n(seq? [1 2 3]) ; =&gt; false\n</code></pre> <p>Sequences are an interface for logical lists, which can be lazy. \"Lazy\" means that a sequence of values are not evaluated until accessed.</p> <p>A lazy sequence enables the use of large or even an infinite series, like so:</p> <p>Lazy sequences</p> <pre><code>(range) ; =&gt; (0 1 2 3 4 ...) - an infinite series\n(take 4 (range)) ;  (0 1 2 3) - lazyily evaluate range and stop when enough values are taken\n</code></pre> <p>Use cons to add an item to the beginning of a list or vector</p> <pre><code>(cons 4 [1 2 3]) ; =&gt; (4 1 2 3)\n(cons 4 '(1 2 3)) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use conj to add an item relative to the type of collection, to the beginning of a list or the end of a vector</p> <pre><code>(conj [1 2 3] 4) ; =&gt; [1 2 3 4]\n(conj '(1 2 3) 4) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use concat to add lists or vectors together</p> <pre><code>(concat [1 2] '(3 4)) ; =&gt; (1 2 3 4)\n</code></pre> <p>Use filter, map to interact with collections</p> <pre><code>(map inc [1 2 3]) ; =&gt; (2 3 4)\n(filter even? [1 2 3]) ; =&gt; (2)\n</code></pre> <p>Use reduce to reduce them</p> <pre><code>(reduce + [1 2 3 4])\n; = (+ (+ (+ 1 2) 3) 4)\n; =&gt; 10\n</code></pre> <p>Reduce can take an initial-value argument too</p> <pre><code>(reduce conj [] '(3 2 1))\n; =&gt; [3 2 1]\n</code></pre> <p>Equivalent of <code>(conj (conj (conj [] 3) 2) 1)</code></p>"},{"location":"introduction/clojure-in-15-minutes/#annonymous-functions","title":"Annonymous Functions","text":"<p>Use <code>fn</code> to create new functions that defines some behaviour. <code>fn</code> is referred to as an anonymous fuction as it has no external name to be referenced by and must be called within a list form.</p> <pre><code>(fn hello [] \"Hello World\")\n</code></pre> <p>Wrap a <code>(fn ,,,)</code> form in parens to call it and return the result.</p> <p>Call an anonymous function</p> <pre><code>((fn hello [] \"Hello World\")) ; =&gt; \"Hello World\"\n</code></pre> <p>Normally the anonymous function is used inline with other code</p> <p>Use anonymous function within other code</p> <pre><code>(map (fn [x] (* x 2)) [1 2 3 4  [1 2 3 4 5]5])\n</code></pre> <p>Make the anonymous function reusable by binding it to a shared name (<code>var</code>) using <code>def</code>.</p> <p>The <code>var</code> name bound to the function can now be called anywhere in the namespace.</p> <p>As <code>def</code> creates a <code>var</code> (variable) name, the developer can changed the expression the name is bound to and re-evaluated to use the changed behaviour.</p> <p>Bind a name to the anonymous function</p> <pre><code>(def hello-world\n  (fn hello [] \"Hello World\"))\n</code></pre> <p>Evaluate annonymous function by evaluating its name</p> <pre><code>hello-world\n</code></pre> <p>NOTE: <code>hello-world</code> is a name and not a function call, so parentheses are not required.</p>"},{"location":"introduction/clojure-in-15-minutes/#shared-functions","title":"Shared Functions","text":"<p>It is more common to use the <code>defn</code> macro to define a function.  This is the same as defining the <code>fn</code> function and the <code>def</code> name within the same expression</p> <p>Define a function with defn macro</p> <pre><code>(defn hello-world\n  \"I am a humble doc-string, please describe the function purpose\"\n []\n \"Hello World\")\n</code></pre> <p><code>#'user/hello-world</code> is the value returned from evaluating the expression, showing the fully qualified name of the function.  Note: the fully qualified name will be different when defined in a differnt namespace than <code>user</code>.</p> <p>A <code>defn</code> function has the scope of the current namespace, so can be called anywhere in the namespace or in a namepace that has used <code>require</code> to include this namespace.</p> <p>Call a function</p> <pre><code>(hello-world)\n</code></pre> <p>The <code>[]</code> vector is used to define the argument names for the function.  There can be zero or more arguments.</p> <p>Call function with arguments</p> <pre><code>(defn hello [name]\n  (str \"Hello \" name))\n</code></pre> <p>The correct number of arguments must be used when calling a function, or an error will be returned.</p> <p>Call function with arguments</p> <pre><code>(hello \"Steve\") ; =&gt; \"Hello Steve\"\n</code></pre> Pass a hash-map as an argument <p>Simplify the design of a function signature by passing all arguments as a hash-map. <pre><code>(defn data-processing\n  [data]\n  (let [body (get data :body)])\n    (transform body))\n</code></pre>  Associative Destructuring can be used to automatically create local variables from the desired keys contained in the map, giving access to the value of each key. <pre><code>(defn data-processing\n  [{:keys [body]}]\n  (transform body))\n</code></pre></p> <p>Clojure supports  multi-variadic functions, allowing one function definition to respond to a function call with different number of arguments.  This provides a simple form of polymorphism based on the number of arguments.</p> <pre><code>(defn hello-polly\n  ([] \"Hello World\")  ; (1)!\n  ([name] (str \"Hello \" name))) ; (2)!\n</code></pre> <ol> <li> <p>Call <code>hello-polly</code> with one argument      <pre><code>(hello-polly \"Jake\") ; =&gt; \"Hello Jake\"\n</code></pre></p> </li> <li> <p>Call <code>hello-polly</code> with zero arguments      <pre><code>(hello-polly) ; =&gt; \"Hello World\"\n</code></pre></p> </li> </ol> <p>Functions can pack extra arguments up in a seq for you</p> <pre><code>(defn count-args [&amp; args]\n  (str \"You passed \" (count args) \" args: \" args))\n(count-args 1 2 3) ; =&gt; \"You passed 3 args: (1 2 3)\"\n</code></pre> <p>You can mix regular and packed arguments</p> <pre><code>(defn hello-count [name &amp; args]\n  (str \"Hello \" name \", you passed \" (count args) \" extra args\"))\n(hello-count \"Finn\" 1 2 3)\n; =&gt; \"Hello Finn, you passed 3 extra args\"\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#hash-map-collections","title":"Hash-map collections","text":"<pre><code>(class {:a 1 :b 2 :c 3}) ; =&gt; clojure.lang.PersistentArrayMap\n</code></pre> <p>Keywords are like strings with some efficiency bonuses</p> <pre><code>(class :a) ; =&gt; clojure.lang.Keyword\n</code></pre> <p>Maps can use any type as a key, but usually keywords are best</p> <pre><code>(def stringmap (hash-map \"a\" 1, \"b\" 2, \"c\" 3))\nstringmap  ; =&gt; {\"a\" 1, \"b\" 2, \"c\" 3}\n\n(def keymap (hash-map :a 1 :b 2 :c 3))\nkeymap ; =&gt; {:a 1, :c 3, :b 2} (order is not guaranteed)\n</code></pre> Commas are whitespace <p>commas are always treated as whitespace and are ignored by the Clojure reader</p> <p>Retrieve a value from a map by calling it as a function</p> <pre><code>(stringmap \"a\") ; =&gt; 1\n(keymap :a) ; =&gt; 1\n</code></pre> <p>Keywords can be used to retrieve their value from a map.  Strings cannot be used.</p> <pre><code>(:b keymap) ; =&gt; 2\n\n(\"a\" stringmap)\n; =&gt; Exception: java.lang.String cannot be cast to clojure.lang.IFn\n</code></pre> <p>Retrieving a non-present value returns nil</p> <pre><code>(stringmap \"d\") ; =&gt; nil\n</code></pre> <p>Use assoc to add new keys to hash-maps</p> <pre><code>(assoc keymap :d 4) ; =&gt; {:a 1, :b 2, :c 3, :d 4}\n</code></pre> <p>But remember, clojure types are immutable!</p> <pre><code>keymap ; =&gt; {:a 1, :b 2, :c 3}\n</code></pre> <p>Use dissoc to remove keys</p> <pre><code>(dissoc keymap :a :b) ; =&gt; {:c 3}\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#sets","title":"Sets","text":"<pre><code>(class #{1 2 3}) ; =&gt; clojure.lang.PersistentHashSet\n(set [1 2 3 1 2 3 3 2 1 3 2 1]) ; =&gt; #{1 2 3}\n</code></pre> <p>Add a member with conj</p> <pre><code>(conj #{1 2 3} 4) ; =&gt; #{1 2 3 4}\n</code></pre> <p>Remove one with disj</p> <pre><code>(disj #{1 2 3} 1) ; =&gt; #{2 3}\n````\n\nTest for existence by using the set as a function:\n\n```clojure\n(#{1 2 3} 1) ; =&gt; 1\n(#{1 2 3} 4) ; =&gt; nil\n</code></pre> <p>There are more functions in the clojure.sets namespace.</p>"},{"location":"introduction/clojure-in-15-minutes/#useful-forms","title":"Useful forms","text":"<p>Logic constructs in clojure are just macros, and look like everything else</p> <pre><code>(if false \"a\" \"b\") ; =&gt; \"b\"\n(if false \"a\") ; =&gt; nil\n</code></pre> <p>Use let to create temporary bindings</p> <pre><code>(let [a 1 b 2]\n  (&gt; a b)) ; =&gt; false\n</code></pre> <p>Group statements together with do</p> <pre><code>(do\n  (print \"Hello\")\n  \"World\") ; =&gt; \"World\" (prints \"Hello\")\n</code></pre> <p>Functions have an implicit do</p> <pre><code>(defn print-and-say-hello [name]\n  (print \"Saying hello to \" name)\n  (str \"Hello \" name))\n(print-and-say-hello \"Jeff\") ;=&gt; \"Hello Jeff\" (prints \"Saying hello to Jeff\")\n</code></pre> <p>So does let</p> <pre><code>(let [name \"Urkel\"]\n  (print \"Saying hello to \" name)\n  (str \"Hello \" name)) ; =&gt; \"Hello Urkel\" (prints \"Saying hello to Urkel\")\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#namespaces-and-libraries","title":"Namespaces and Libraries","text":"<p>Namespaces are used to organise code into logical groups.  The top of each Clojure file has an <code>ns</code> form that defines the namespace name.  The domain part of the namespace name is typically the organisation or community name (e.g. GitHub user/organisation)</p> <pre><code>(ns domain.namespace-name)\n</code></pre> <p>All Practicalli projects have namespace domains of <code>practicalli</code></p> <pre><code>(ns practicalli.service-name)\n</code></pre> <p><code>require</code> allows code from one namespace to be accessed from another namespace, either from a the same Clojure project or from a library added to the project classpath.</p> <p>The <code>:as</code> directive with <code>require</code> is used to specify an alias name, a short-hand for the full library name</p> <p>Or <code>:refer [function-name var-name]</code> can be used to specify specific functions and data (vars) that are available directly</p> <p>A required directive is typically added to a namespace form</p> <pre><code>(ns practicalli.service-name\n  (require [clojure.set :as set]))\n</code></pre> <p>The functions from clojure.set can be used via the alias name, rather than the fully qualified name, i.e. <code>clojure.set/intersection</code></p> <pre><code>(set/intersection #{1 2 3} #{2 3 4}) ; =&gt; #{2 3}\n(set/difference #{1 2 3} #{2 3 4}) ; =&gt; #{1}\n</code></pre> <p><code>:require</code> directive can be used to include multiple library namespaces</p> <pre><code>(ns test\n  (:require\n    [clojure.string :as string]\n    [clojure.set :as set]))\n</code></pre> <p><code>require</code> can be used by itself, usually within a rich code block</p> <pre><code>(comment\n  (require 'clojure.set :as set))\n</code></pre>"},{"location":"introduction/clojure-in-15-minutes/#strong-dynamic-types","title":"Strong Dynamic Types","text":"<p>Clojure is strongly typed, so everything is a type in Clojure.</p> <p>Clojure is dynamically typed, so Clojure infers the type.  A type does not need to be specified in the code, making the code simpler and more concise.</p> <p>Clojure is a hosted language and uses the type system of the platform it runs upon.  For example, Clojure uses Java object types for booleans, strings and numbers under the covers.</p> <p>Use <code>class</code> or <code>type</code> function to inspect the type of some code in Clojure.</p> <pre><code>(type 1) ; Integer literals are java.lang.Long by default\n(type 1.); Float literals are java.lang.Double\n(type \"\"); Strings always double-quoted, and are java.lang.String\n(type false) ; Booleans are java.lang.Boolean\n(type nil); The \"null\" value is called nil\n</code></pre> <p>Vectors and Lists are java classes too!</p> <pre><code>(type [1 2 3]); =&gt; clojure.lang.PersistentVector\n(type '(1 2 3)); =&gt; clojure.lang.PersistentList\n</code></pre> <p>Type hints</p> <p>Type hints can be used to avoid reflection look-ups where performace critical issues have been identified.  Type hints are not required in general. Clojure Type Hints</p>"},{"location":"introduction/clojure-in-15-minutes/#java-interop","title":"Java Interop","text":"<p>Java has a huge and useful standard library, so you'll want to learn how to get at it.</p> <p>Use import to load a java package</p> <pre><code>(import java.util.Date)\n</code></pre> <p>Or import from a java package name</p> <pre><code>(ns test\n  (:import\n    java.util.Date\n    java.util.Calendar))\n</code></pre> <p>Use the class name with a \".\" at the end to make a new instance</p> <pre><code>(Date.) ; &lt;a date object&gt;\n</code></pre> <p>Use <code>.</code> to call methods. Or, use the \".method\" shortcut</p> <pre><code>(. (Date.) getTime) ; &lt;a timestamp&gt;\n(.getTime (Date.))  ; exactly the same thing.\n</code></pre> <p>Use / to call static methods</p> <pre><code>(System/currentTimeMillis) ; &lt;a timestamp&gt; (system is always present)\n</code></pre> <p>Use doto to make dealing with (mutable) classes more tolerable</p> <pre><code>(import java.util.Calendar)\n(doto (Calendar/getInstance)\n  (.set 2000 1 1 0 0 0)\n  .getTime) ; =&gt; A Date. set to 2000-01-01 00:00:00\n</code></pre>"},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"<p>By submitting content ideas and corrections you are agreeing they can be used in any work by Practicalli under the Creative Commons Attribution ShareAlike 4.0 International license.  Attribution will be detailed via GitHub contributors.</p> <p>Please raise an issue before creating a pull request</p> <p>Raising an issue or post on the #practicalli channel of Clojurians Slack community avoids disappointment if the contribution would not be accepted and saves time for all.</p> <p>Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow.  MkDocs can also run a local server using the <code>make docs</code> target from the <code>Makefile</code></p> <p>All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.</p>"},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"<p>If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.</p> <p>Raising an issue before creating a pull request will save you and the maintainer time.</p> <p>Alternatively, reach out to Practicalli via the <code>#practicalli</code> channel of the Clojurians Slack community.</p> <p>Clojurians Slack community</p>"},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"<p>Pull Request Commits must be cryptographically signed</p> <p>All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.</p> <p>Configure commit signing with SSH key - Practicalli Engineering</p> <p>All pull requests must include an entry in CHANGELOG.md or will not be merged.  A changelog entry allows the community to follow the changes to the book.</p> <p>Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.</p> <p>Please keep pull requests small and focused, as they are much quicker to review and easier to accept.  Ideally PR's should be for a specific page or at most a section.</p> <p>A PR with a list of changes across different sections will be closed without merging as these take considerable time to review.</p> <p>Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged.  Raise an issue, or post a thread in the  Clojurians Slack #practicall channel</p>"},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"<p>A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language.  </p> <p>The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions.  I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.</p> <p>Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.</p> <p>Special thanks to Bruce Durling for getting me into Cloure in the first place.</p> <p></p>"},{"location":"introduction/first-taste-of-clojure/","title":"Clojure Quick Reference","text":"<p>The basic Clojure syntax and a few common functions you should probably learn first.</p> <p>The examples are editable (using an embedded REPL) so feel free to experiment and watch as the return value changes as you change the code.  Reload the page if you want to reset all the code back to the starting point.</p> <p>Install Clojure on your computer if you want to experiment even further.</p> <p>Want to go deeper already?</p> <p>Watch the Clojure language video series by Brian Will for a detailed introduction to key parts of the language.  Or discover Clojure core functions by completing challenges on 4Clojure.org and then watching how Practicalli solved them.</p>"},{"location":"introduction/first-taste-of-clojure/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is a call to a function.  Any other elements are passed to the function as arguments. The examples show how to call functions with multiple arguments.</p> <pre><code>(+ 1 2)\n</code></pre> <pre><code>(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n</code></pre> <pre><code>(str \"Clojure is \" (- 2021 2007) \" years old\")\n</code></pre> <pre><code>(inc 1)\n</code></pre> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <pre><code>(filter odd? (range 11))\n</code></pre> <p>Prefix notation and parens</p> <p>Hugging code with <code>()</code> is a simple syntax to define the scope of code expressions.  No additional <code>;</code>, <code>,</code> or spaces are required.</p> <p>Treating the first element of a list as a function call is referred to as prefix notation, which greatly simplifies Clojure syntax.  Prefix notation makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p>"},{"location":"introduction/first-taste-of-clojure/#understanding-functions","title":"Understanding functions","text":"<p><code>clojure.repl/doc</code> function returns the doc-string of the given function. A doc-string should be part of all public function definitions.</p> <p>Clojure editors should provide commands to view doc-strings and the ability to jump to function definitions to view their source code</p> <pre><code>(clojure.repl/ddoc doc)\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <p>A list, <code>()</code>, used for calling functions and representing sequences. A linked list for sequential access.</p> <pre><code>(str \"lists used mainly \" (* 2 2) \" \" :code)\n</code></pre> <p>A vector, <code>[]</code>, used for simple collections of values.  An indexed data structure for random access</p> <pre><code>[0 \"indexed\" :array (* 2 2) \"random-access\" 4 :data]\n</code></pre> <p>A map, <code>{}</code>, use for descriptive data collections.  An associative data structure for value lookup by unique keys (also known as a dictionary).</p> <pre><code>{ :hash-map :associative-collection :pairs {:key \"value\"} :aka \"dictionary\"}\n</code></pre> <p>A set, <code>#{}</code>, use as a unique set of values. Sets are used to test if a value is contained within, i.e. predicates.</p> <pre><code>#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre> <p>Persistent data types</p> <p>Values are immutable so when a function changes a value a new immutable value is created. When creating new collection values, unchanged values are shared with the original collection.  This sharing model is called persistent data types and enables immutable data to be used efficiently.</p>"},{"location":"introduction/first-taste-of-clojure/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p> <p><code>map</code> <code>reduce</code> <code>filter</code> are common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n</code></pre> <pre><code>(filter even? [1 3 5 8 13 21 34])\n</code></pre> <pre><code>(reduce + [31 28 30 31 30 31])\n</code></pre> <pre><code>(empty? [])\n</code></pre> <p>Many Clojure core functions for collections</p> <p><code>map</code>, <code>reduce</code>, <code>apply</code>, <code>filter</code>, <code>remove</code> are just a few examples of Clojure core functions that work with data structures.</p>"},{"location":"introduction/first-taste-of-clojure/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(map (fn [number] (* number number)) [1 2 3 4 5])\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#defining-local-names","title":"Defining local names","text":"<p>Use the <code>let</code> function as a simple way to experiment with code designs</p> <pre><code>(let [data (range 24 188)\n      total (reduce + data)\n      values (count data)]\n  (str \"Average value: \" (/ total values)))\n</code></pre> <p>Define local names to remove duplication in function definitions, or to simplify algorithms</p> <pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>A name bound to a value can be used to represent that value throughout the code.  Names can be bound to simple values (numbers, strings, etc.), collections or even function calls.</p> <p><code>def</code> binds a name to a value with the scope of the current namespace.  <code>def</code> is useful for data that is passed to multiple functions within a namespace.</p> <p>Evaluating a name will return the value it is bound to.</p> <pre><code>(def public-health-data\n  [{:date \"2020-01-01\" :confirmed-cases 23814 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 24329 :recovery-percent 14}\n   {:date \"2020-01-03\" :confirmed-cases 25057 :recovery-percent 12}])\n\npublic-health-data\n</code></pre> <p>def for shared values, let for locally scoped values</p> <p><code>let</code> function is used to bind names to values locally, such as within a function definition.  Names bound with <code>def</code> have namespace scope so can be used with any code in that namespace.</p>"},{"location":"introduction/first-taste-of-clojure/#iterating-over-collections","title":"Iterating over collections","text":"<p><code>map</code> iterates a function over a collection of values, returning a new collection of values</p> <pre><code>(map inc (range 20))\n</code></pre> <p><code>reduce</code> iterates a function over the values of a collection to produce a new result</p> <pre><code>(reduce + (range 101))\n</code></pre> <p>Reducing functions are function definitions used by the <code>reduce</code> function over a collection</p> <pre><code>(reduce (fn [[numerator denominator] accumulator]\n          [(+ numerator accumulator)\n           (inc denominator)])\n        [0 0]\n        (range 1 20))\n</code></pre> <p>Functions can call themselves to iterate over a collection.  Using a lazy sequence means only the required numbers are generated, ensuring efficiency of operation and making the function usable in many different scenarios.</p> <pre><code>(defn fibonacci-sequence\n  [current-number next-number]\n  (lazy-seq\n    (cons current-number\n          (fibonacci-sequence next-number (+ current-number next-number)))))\n\n(take 10 (fibonacci-sequence 0 1))\n</code></pre>"},{"location":"introduction/first-taste-of-clojure/#host-interoperability","title":"Host Interoperability","text":"<p>The REPL in this web page is running inside a JavaScript engine, so JavaScript functions can be used from within ClojureScript code (ClojureScript is Clojure that runs in JavaScript environments).</p> <p>In the box below, replace <code>()</code> with <code>(js/alert \"I am a pop-up alert\")</code></p> <pre><code>()\n</code></pre> <p>Java libraries in Clojure</p> <p>java.lang library is available in Clojure by default and many other Java methods can be included by using their full name, e.g. <code>(java.lang.Date.)</code> will return the current date.</p>"},{"location":"introduction/first-taste-of-clojure/#next-steps","title":"Next steps","text":"<p>Install Clojure on your computer if you want to experiment even further or keep on reading more about Clojure.</p>"},{"location":"introduction/five-steps-to-clojure/","title":"5 Steps to Clojure","text":""},{"location":"introduction/five-steps-to-clojure/#set-up-your-environment","title":"Set up your environment","text":"<p>Install Clojure and a build tool</p> <p>Setup a Clojure aware editor</p> <ul> <li>Emacs &amp; CIDER - Spacemacs, Doom, Prelude</li> <li>Neovim &amp; Conjure</li> <li>VSCode &amp; Clover or Calva</li> <li>Sublime Text &amp; SublimedClojure</li> </ul>"},{"location":"introduction/five-steps-to-clojure/#learn-the-syntax","title":"Learn the syntax","text":""},{"location":"introduction/five-steps-to-clojure/#practice-the-core-functions","title":"Practice the core functions","text":"<ul> <li>4clojure.org</li> <li>Exercism.io</li> </ul>"},{"location":"introduction/five-steps-to-clojure/#def-defn-let","title":"def / defn / let","text":""},{"location":"introduction/five-steps-to-clojure/#map-reduce-apply","title":"map / reduce / apply","text":""},{"location":"introduction/five-steps-to-clojure/#for-while-loop-recur","title":"for / while / loop / recur","text":""},{"location":"introduction/five-steps-to-clojure/#adopt-functional-programming-practices","title":"Adopt functional programming practices","text":""},{"location":"introduction/five-steps-to-clojure/#learn-the-commonly-used-libraries","title":"Learn the commonly used libraries","text":""},{"location":"introduction/five-steps-to-clojure/#server-side-websites","title":"Server-side websites","text":""},{"location":"introduction/five-steps-to-clojure/#ring-compojure-reitit-hiccup-selma","title":"Ring / Compojure / Reitit / Hiccup | Selma","text":""},{"location":"introduction/five-steps-to-clojure/#react-client-side-single-page-apps","title":"React client-side single page apps","text":""},{"location":"introduction/five-steps-to-clojure/#reactjs-om-next-reagent-re-frame","title":"React.js / Om-next / Reagent / Re-frame","text":""},{"location":"introduction/five-steps-to-clojure/#coreasync","title":"core.async","text":""},{"location":"introduction/five-steps-to-clojure/#full-stack-apps","title":"Full Stack apps","text":""},{"location":"introduction/five-steps-to-clojure/#kit-framework","title":"Kit Framework","text":""},{"location":"introduction/learning-clojure/","title":"Learning Clojure","text":"<p>Learning the syntax of Clojure is really quick (its very small and simple).  Learning to think functionally and discovering the 700+ functions in the Clojure API can take a little longer.  I recommend you find someone with a bit of Clojure experience to guide you.</p> <p>Here is my suggested path to learning Clojure and thinking functionally.  Many of the tasks can be done in parallel.</p>"},{"location":"introduction/learning-clojure/#simple-rather-than-complex-the-foundation-of-clojure","title":"Simple rather than complex - the foundation of Clojure","text":"<p>Gaining an appreciation that systems should be simple is a crucial step truly understanding Clojure.  So early in your journey into Clojure, spend an hour watching Rich Hickey talk about Simple made Easy - (transcript of talk).</p>"},{"location":"introduction/learning-clojure/#experience-the-clojure-syntax","title":"Experience the Clojure syntax","text":"<p>Take a quick look at the Syntax of Clojure.  The syntax is very small, so this will take about 15 minutes to 1 hour (dependent on your own experiences with coding).  Don't try to remember all the syntax, it will come through practise.</p> <ul> <li>eg. Clojure in 15 minutes</li> </ul>"},{"location":"introduction/learning-clojure/#set-up-an-enjoyable-environment-to-work-in","title":"Set up an enjoyable environment to work in","text":"<p>Find how to use Clojure with your favourite editor or IDE.  Configure this tool so you can easily run a REPL and evaluate some expressions.</p> <ul> <li>repl.it - web based repl you can share / fork</li> <li>Spacemacs - for the ultimate Emacs &amp; Vim experience</li> <li>IntelliJ and Cursive</li> <li>Leiningen &amp; any editor you like</li> </ul>"},{"location":"introduction/learning-clojure/#building-a-frame-of-reference-for-functional-programming","title":"Building a frame of reference for functional programming","text":"<p>Find an introductory book that you like which provides lots of example code to help you feel more comfortable with the syntax and more importantly the major concepts of functional programming with Clojure.  Type in the exercises as you read and don't be afraid to play around with code examples</p> <ul> <li>Clojure for the Brave and the True</li> <li>Living Clojure - includes a training guide</li> <li>Practicalli Clojure - you are already here :)</li> <li>ClojureBridge London workshop - aimed at those new to coding</li> <li>PurelyFunctional - Introduction to Clojure</li> </ul>"},{"location":"introduction/learning-clojure/#practice-clojure-standard-library-clojurecore","title":"Practice Clojure standard library (clojure.core)","text":"<p>Practice Clojure.  Write lots of small and relatively simple examples in Clojure and experiment with the code in the REPL and try break things.  This will start helping you learn the Clojure API</p> <p>You should become comfortable in your understanding of:</p> <ul> <li>basic values (strings, numbers, etc) and persistent collections (list, vector, map, set)</li> <li>binding names to values and their scope  (def, defn, let)</li> <li>calling functions, defining functions, arity options for functions</li> <li>Higher order functions and basics of functional composition (map, reduce, filter, etc)</li> <li>Designing with data, Extensible Data Notation (EDN), data manipulation</li> </ul> <p>Activities to help practice Clojure include:</p> <ul> <li>4Clojure.org - aim to complete the first 50 exercises, the first 10 are relatively easy</li> <li>Coding Kata exercises</li> <li>Awesome Kata collection</li> <li>Alice In Wonderland inspired Katas</li> <li>Attend coding dojo events - e.g. London Clojurians</li> </ul>"},{"location":"introduction/learning-clojure/#solidify-some-of-the-basics-you-have-learned-so-far","title":"Solidify some of the basics you have learned so far","text":"<p>Work on a relatively small project that you care about enough to work on</p> <ul> <li>eg. a tool to help you at work</li> </ul>"},{"location":"introduction/learning-clojure/#learn-more-tools-to-help-you-think-functionally","title":"Learn more tools to help you think functionally","text":"<ul> <li>mostly using immutable values and pure functions</li> <li>functional composition, sequences and transducers</li> <li>atoms for managing mutable state changes (with immutable values)</li> </ul>"},{"location":"introduction/learning-clojure/#get-a-broader-view-of-clojure-and-learn-some-common-practices","title":"Get a broader view of Clojure and learn some common practices","text":"<p>Start reading a book which is aimed at intermediate</p> <ul> <li>Clojure CookBook</li> </ul> <p>Watch Video's about Clojure on subjects that are relevant to work or projects you want to work on.</p> <ul> <li>ClojureTV on YouTube</li> </ul> <p>Follow tutorials on Clojure, especially those that introduce the amazing libraries available in Clojure</p> <ul> <li>Lambda Island</li> <li>PurelyFunctional.tv</li> <li>Practical.li</li> </ul> <p>Work with some of the most common libraries in Clojure</p> <ul> <li>Ring / Compojure for web development (server side)</li> <li>ClojureScript for web UI or native mobile apps (client side)</li> <li>Reagent - reactjs style single page apps<ul> <li>Reagent deep dive - excellent tutorial</li> </ul> </li> <li>core.async - for asynchronous programming</li> <li>clojure.string - specific functions for string manipulation</li> <li>tools.logging</li> <li>java.jdbc - database access</li> <li>data.zip - manipulating trees of data, e.g. XML</li> </ul>"},{"location":"introduction/repl-workflow/","title":"REPL Driven Development","text":"<p>Always be REPL'ing</p> <p>Coding without a REPL feels limiting. The REPL provides fast feedback from code as its crafted, testing assumptions and design choices every step of the journey to a solution  - John Stevenson, Practical.li</p> <p>Clojure is a powerful, fun and highly productive language for developing applications and services.  The clear language design is supported by a powerful development environment known as the REPL (read, evaluate, print, loop).  The REPL gives you instant feedback on what your code does and enables you to test either a single expression or run the whole application (including tests).</p> <p>REPL driven development is the foundation of working with Clojure effectively</p> <p>An effective Clojure workflow begins by running a REPL process.  Clojure expressions are written and evaluated immediately to provide instant feedback. The REPL feedback helps test the assumptions that are driving the design choices.</p> <ul> <li>Read - code is read by the Clojure reader, passing any macros to the macro reader which converts those macros into Clojure code.</li> <li>Evaluate - code is compiled into the host language (e.g. Java bytecode) and executed</li> <li>Print - results of the code are displayed, either in the REPL or as part of the application.</li> <li>Loop - the REPL is a continuous process that evaluates code, either a single expression or the whole application.</li> </ul> <p>Design decisions and valuable data from REPL experiments can be codified as specifications and unit tests</p> <p>Practicalli REPL Reloaded Workflow</p> <p>The principles of REPL driven development are implemented in practice using the Practicalli REPL Reloaded Workflow and supporting tooling.  This workflow uses Portal to inspect all evaluation results and log events, hot-load libraries into the running REPL process and reloads namespaces to support major refactor changes.</p>"},{"location":"introduction/repl-workflow/#evaluating-source-code","title":"Evaluating source code","text":"<p>A REPL connected editor is the primary tool for evaluating Clojure code from source code files, displaying the results inline.</p> <p>Source code is automatically evaluated in its respective namespace, removing the need to change namespaces in the REPL with (<code>in-ns</code>) or use fully qualified names to call functions.</p> <p> </p> Evaluate Clojure in a Terminal UI REPL <p>Entering expressions at the REPL prompt evaluates the expression immediately, returning the result directly underneath  </p>"},{"location":"introduction/repl-workflow/#rich-comment-blocks-living-documentation","title":"Rich Comment blocks - living documentation","text":"<p>The <code>(comment ,,,)</code> function wraps code that is only run directly by the developer using a Clojure aware editor.</p> <p>Expressions in rich comment blocks can represent how to use the functions that make up the namespace API.  For example, starting/restarting the system, updating the database, etc.  Expressions provide examples of calling functions with typical arguments and make a project more accessible and easier to work with.</p> <p>Clojure Rich Comment to manage a service</p> <pre><code>(ns practicalli.gameboard.service)\n\n(defn app-server-start [port] ,,,)\n(defn app-server-start [] ,,,)\n(defn app-server-restart [] ,,,)\n\n(defn -main\n  \"Start the service using system components\"\n  [&amp; options] ,,,)\n\n(comment\n  (-main)\n  (app-server-start 8888)\n  (app-server-stop)\n  (app-server-restart 8888)\n\n  (System/getenv \"PORT\")\n  (def environment (System/getenv))\n  (def system-properties (System/getProperties))\n  ) ; End of rich comment block\n</code></pre> <p>Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide clj-kondo linter warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n  (defn value-added-tax []\n    ;; algorithm design - first idea)\n\n  (defn value-added-tax []\n    ;; algorithm design - second idea)\n\n  ) ;; End of rich comment block\n</code></pre> <p>The \"Rich\" in the name is an honourary mention to Rich Hickey, the author and benevolent dictator of Clojure design.</p>"},{"location":"introduction/repl-workflow/#design-journal","title":"Design Journal","text":"<p>A journal of design decisions makes the code easier to understand and maintain.  Code examples of design decisions and alternative design discussions are captured, reducing the time spent revisiting those discussions.</p> <p>Journals simplify the developer on-boarding processes as the journey through design decisions are already documented.</p> <p>A Design Journal is usually created in a separate namespace, although it may start as a rich comment at the bottom of a namespace.</p> <p>A journal should cover the following aspects</p> <ul> <li>Relevant expressions use to test assumptions about design options.</li> <li>Examples of design choices not taken and discussions why (saves repeating the same design discussions)</li> <li>Expressions that can be evaluated to explain how a function or parts of a function work</li> </ul> <p>The design journal can be used to create meaningful documentation for the project very easily and should prevent time spent on repeating the same conversations.</p> <p>Example design journal</p> <p>Design journal for TicTacToe game using Reagent, ClojureScript and Scalable Vector Graphics</p>"},{"location":"introduction/repl-workflow/#viewing-data-structures","title":"Viewing data structures","text":"<p>Pretty print shows the structure of results from function calls in a human-friendly form, making it easier for a developer to parse and more likely to notice incorrect results.</p> <p>Tools to view and navigate code</p> <ul> <li> Cider inspector is an effective way to navigate nested data and page through large data sets.</li> <li> Portal Inspector to visualise many kinds of data in many different forms.</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#code-style-and-idiomatic-clojure","title":"Code Style and idiomatic Clojure","text":"<p>Clojure aware editors should automatically apply formatting that follows the  Clojure Style guide.</p> <p>Live linting with clj-kondo suggests common idioms and highlights a wide range of syntax errors as code is written, minimizing bugs and therefore speeding up the development process.</p> <p> </p> <p>Clojure LSP is build on top of clj-kondo</p> <p> Clojure LSP uses clj-kondo static analysis to provide a standard set of development tools (format, refactor, auto-complete, syntax highlighting, syntax &amp; idiom warnings, code navigation, etc).</p> <p>Clojure LSP can be used with any Clojure aware editor that provides an LSP client, e.g.  Spacemacs,  Doom Emacs,  Neovim, VSCode.</p> <p>Clojure Style Guide</p> <p>The  Clojure Style guide provides examples of common formatting approaches, although the development team should decide which of these to adopt.  Emacs <code>clojure-mode</code> will automatically format code and so will Clojure LSP (via cljfmt).  These tools are configurable and should be tailored to the teams standard.</p>"},{"location":"introduction/repl-workflow/#data-and-function-specifications","title":"Data and Function specifications","text":"<p> Clojure spec is used to define a contract on incoming and outgoing data, to ensure it is of the correct form.</p> <p>As data structures are identified in REPL experiments, create data specification to validate the keys and value types of that data.</p> <pre><code>;; ---------------------------------------------------\n;; Address specifications\n(spec/def ::house-number string?)\n(spec/def ::street string?)\n(spec/def ::postal-code string?)\n(spec/def ::city string?)\n(spec/def ::country string?)\n(spec/def ::additional string?)\n\n(spec/def ::address   ; Composite data specification\n  (spec/keys\n   :req-un [::street ::postal-code ::city ::country]\n   :opt-un [::house-number ::additional]))\n;; ---------------------------------------------------\n</code></pre> <p>As the public API is designed, specifications for each functions arguments are added to validate the correct data is used when calling those functions.</p> <p> Generative testing provides a far greater scope of test values used incorporated into unit tests. Data uses clojure.spec to randomly generate data for testing on each test run.</p>"},{"location":"introduction/repl-workflow/#test-driven-development-and-repl-driven-development","title":"Test Driven Development and REPL Driven Development","text":"<p>Test Driven Development (TDD) and REPL Driven Development (RDD) complement each other as they both encourage incremental changes and continuous feedback.</p> <p>Test Driven Development fits well with Hammock Time, as good design comes from deep thought</p> <ul> <li>RDD enables rapid design experiments so different approaches can easily and quickly be evaluated .</li> <li>TDD focuses the results of the REPL experiments into design decisions, codified as unit tests.  These tests guide the correctness of specific implementations and provide critical feedback when changes break that design.</li> </ul> <p> Unit tests should support the public API of each namespace in a project to help prevent regressions in the code.  Its far more efficient in terms of thinking time to define unit tests as the design starts to stabilize than as an after thought.</p> <p><code>clojure.test</code> library is part of the Clojure standard library that provides a simple way to start writing unit tests.</p> <p> Clojure spec can also be used for generative testing, providing far greater scope in values used when running unit tests.  Specifications can be defined for values and functions.</p> <p>Clojure has a number of  test runners available.  Kaocha is a test runner that will run unit tests and function specification checks.</p> <p>Automate local test runner</p> <p>Use  kaocha test runner in watch mode to run tests and specification check automatically (when changes are saved) <pre><code>clojure -X:test/watch\n</code></pre></p>"},{"location":"introduction/repl-workflow/#continuous-integration-and-deployment","title":"Continuous Integration and Deployment","text":"<p>Add a  continuous integration service to run tests and builds code on every shared commit.  Spin up testable review deployments when commits pushed to a pull request branch, before pushing commits to the main deployment branch, creating an effective pipeline to gain further feedback.</p> <ul> <li> CircleCI provides a simple to use service that supports Clojure projects.</li> <li> GitHub Workflows and GitHub actions marketplace to quickly build a tailored continuous integration service, e.g. Setup Clojure GitHub Action.</li> <li> GitLab CI</li> </ul> <p></p>"},{"location":"introduction/repl-workflow/#live-coding-with-data-stuart-halloway","title":"Live Coding with Data - Stuart Halloway","text":"<p>There are few novel features of programming languages, but each combination has different properties. The combination of dynamic, hosted, functional and extended Lisp in Clojure gives developers the tools for making effective programs. The ways in which Clojure's unique combination of features can yield a highly effective development process.</p> <p>Over more than a decade we have developed an effective approach to writing code in Clojure whose power comes from composing many of its key features. As different as Clojure programs are from e.g. Java programs, so to can and should be the development experience. You are not in Kansas anymore!</p> <p>This talk presents a demonstration of the leverage you can get when writing programs in Clojure, with examples, based on my experiences as a core developer of Clojure and Datomic.</p> <p> </p>"},{"location":"introduction/who-uses-clojure/","title":"Who uses Clojure","text":"<p>Hundreds of companies actively advertised their Clojure adoption. Given the broad participation in user groups there are clearly many more organizations using Clojure at some level in their technology stack.</p> <p>A quick scan of various job sites shows Clojure positions at companies like Walmart, Facebook, Staples, Consumer Reports, Salesforce, and Amazon. It doesn't get much more mainstream than that.</p> <p>If you are looking for a new role using Clojure or other functional programming languages, visit Functional Works, the only Functional Recruiters in the world.</p> <p>Here is just a small and diverse set of example companies that I am aware of that use Clojure for development.</p> Company Type of applications Boeing Boeing 737 MAX - onboard maintenance Puppet Labs DevOps apps &amp; services e.g. trapperkeeper Cisco Malware analysis &amp; threat intelligence platform (expert system with core.logic) Deuche Bank (UK) Processing event streams from Apache Storm Atlassian Collaborative editing platform for all their products Netflix Map-Reduce languages for writing apps for Hadoop / Pig USwitch (UK) Creating meaningful data from multiple sources Daily Mail Online (UK) Publishing pipeline Circle CI (USA) Front-end of CI server in ClojureScript &amp; test suite CitiGroup Financial Trading Student Loans company (UK) Loans management system written in Clojure LinkedIn Powers the LinkedIn social graph Walmart (USA) eReceipts project to process every purchase from 5,000+ stores SwiftKey (UK) Predictive intelligence platform (possibly used with Microsoft Cortana) Roomkey.co.uk Hotel booking system to rival Expedia (with a tiny development team) Funding Circle (UK &amp; USA) Adopting Clojure as their main language (from Ruby, etc) Braintree Payment processing pipeline with Kafka Mastodon C Data centre analysis (Incanta, Storm) Thoughtworks Agile development for Client projects world wide Vero Insurance (AUS) Rebuilt policy management system in Clojure with Thoughworks Meta-X Performance art (Overtone, Quil) Salesforce (USA) Build &amp; deployment with Puppet &amp; Application Routing with nginx-clojure <p>There are many more examples of projects on the HackerNews thread: Ask HN: Who's using Clojure in Production</p>"},{"location":"introduction/who-uses-clojure/#tech-radar","title":"Tech Radar","text":"<p>Clojure is also defined as a technology that can be adopted since 2014, according to the Thoughtworks technology radar.</p> <p></p> <p>JUXT also created its own Clojure specific technology radar as there is such an encompassing ecosystem of libraries and services.</p>"},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"<p>Making the docs more engaging using the mkdocs-material theme reference guide</p> Configuring Colors <p>Material for MkDocs - Changing the colors lists the primary and accent colors available.</p> <p>HSL Color Picker for codes to modify the theme style, overriding colors in <code>docs/assets/stylesheets/extra.css</code></p>"},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"<p>Links open in the same browser window/tab by default.</p> <p>Add <code>{target=_blank}</code> to the end of a link to configure opening in a new tab</p> <pre><code>[link text](url){target=_blank}\n</code></pre>"},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"<p>Convert any link into a button by adding <code>{.md-button}</code> class names to end of the markdown for a link, which uses <code>.md-button-primary</code> by default.  Include <code>target=_blank</code> for buttons with links to external sites.</p> <pre><code>[link text](http://practical.li/blog){.md-button target=_blank}\n</code></pre> <p>Or specify a different class</p> <pre><code>[link text](http://practical.li/blog){.md-button .md-button-primary}\n</code></pre> <p>Add an icon to the button</p> <p> Practicalli Issues  Practicalli Blog</p> <pre><code>[:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n</code></pre> <p>Search all supported icons</p>"},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"<p>Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position</p> <pre><code>&lt;p style=\"text-align:center\"&gt;\n&lt;iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen&gt;&lt;/iframe&gt;\n&lt;/p&gt;\n</code></pre> <p>mkdocs material does not have direct support for adding a YouTube video via markdown.</p>"},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"<p>Supported admonition types</p> <p>Note</p> <p>Use <code>!!!</code> followed by <code>NOTE</code></p> <p>Adding a title</p> <p>Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> <p>Shh, no title bar just the text... Use <code>!!!</code> followed by <code>NOTE</code> and a <code>\"\"</code> empty double quotes</p> <p>Abstract</p> <p>Use <code>!!!</code> followed by <code>ABSTRACT</code></p> <p>Info</p> <p>Use <code>!!!</code> followed by <code>INFO</code></p> <p>Tip</p> <p>Use <code>!!!</code> followed by <code>TIP</code></p> <p>Success</p> <p>Use <code>!!!</code> followed by <code>SUCCESS</code></p> <p>Question</p> <p>Use <code>!!!</code> followed by <code>QUESTION</code></p> <p>Warning</p> <p>Use <code>!!!</code> followed by <code>WARNING</code></p> <p>Failure</p> <p>Use <code>!!!</code> followed by <code>FAILURE</code></p> <p>Danger</p> <p>Use <code>!!!</code> followed by <code>DANGER</code></p> <p>Bug</p> <p>Use <code>!!!</code> followed by <code>BUG</code></p> <p>Example</p> <p>Use <code>!!!</code> followed by <code>EXAMPLE</code></p> <p>Quote</p> <p>Use <code>!!!</code> followed by <code>QUOTE</code></p>"},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note <p>Collapse those admonitions using <code>???</code> instead of <code>!!!</code></p> Replace with a title <p>Use <code>???</code> followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p> Expanded by default <p>Use <code>???+</code>, note the <code>+</code> character,  followed by <code>NOTE</code> and a <code>\"title in double quotes\"</code></p>"},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"<p>Inline blocks of text to make a very specific callout within text</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Adding something to then end of text is probably my favourite</p> <p>Info</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"<p>Code blocks include a copy icon automatically</p> <p>Syntax highlighting in code blocks</p> <pre><code>(defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Give the code block a title using <code>title=\"\"</code> after the backtics and language name</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>We all like line numbers, especially when you can set the starting line</p> src/practicalli/gameboard.clj<pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n</code></pre> <p>Add <code>linenums=42</code> to start line numbers from 42 onward</p> <pre><code>clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n</code></pre>"},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"<p>Annotations in a code block help to highlight important aspects.  Use the comment character for the language followed by a space and a number in brackets</p> <p>For example, in a shell code block, use <code># (1)</code> where 1 is the number of the annotation</p> <p>Use a number after the code block to add the text for the annotation, e.g. <code>1.</code>. Ensure there is a space between the code block and the annotation text.</p> <pre><code>ls -la $HOME/Downloads  # (1)\n</code></pre> <ol> <li> I'm a code annotation! I can contain <code>code</code>, formatted text, images, ... basically anything that can be written in Markdown.</li> </ol> <p>Code blocks with annotation, add <code>!</code> after the annotation number to suppress the <code>#</code> character</p> <pre><code>(defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n</code></pre> <ol> <li>Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.</li> </ol> <p>GitHub action example with multiple annotations</p> <pre><code>name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n</code></pre> <ol> <li> <p>You can change the name to your liking.</p> </li> <li> <p>At some point, GitHub renamed <code>master</code> to <code>main</code>. If your default branch     is named <code>master</code>, you can safely remove <code>main</code>, vice versa.</p> </li> <li> <p>This is the place to install further [MkDocs plugins] or Markdown     extensions with <code>pip</code> to be used during the build:</p> <pre><code>pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n</code></pre> </li> </ol>"},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"<p>Add highlight line meta data to a code block after the opening backticks and code block language.</p> <p><code>hl_lines=\"2\"</code> highlights line 2 in the codeblock</p> <pre><code>(defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n</code></pre>"},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"<p><code>--8&lt;--</code> in a code block inserts code from a source code file or other text file</p> <p>Specify a local file from the root of the book project (the directory containing mkdocs.yml)</p> Scheduled Version Check GitHub Workflow from source code file scheduled version check<pre><code>\n</code></pre> Practicalli Project Templates Emacs project configuration - .dir-locals.el<pre><code>((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n</code></pre> <p>Code example reuse</p> <p>Use an embedded local or external file (URL) when the same content is required in more than one place in the book.</p> <p>An effective way of sharing code and configuration mutliple times in a book or across multiple books.</p>"},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"<p>Create in page tabs that can also be</p> <p>Setting up a project</p> Clojure CLILeiningen <pre><code>clojure -T:project/new :template app :name practicalli/gameboard\n</code></pre> <pre><code>lein new app practicalli/gameboard\n</code></pre> <p>Or nest the content tabs in an admonition</p> <p>Run a terminal REPL</p> Clojure CLILeiningen <pre><code>clojure -T:repl/rebel\n</code></pre> <pre><code>lein repl\n</code></pre>"},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"<p>Neat flow diagrams</p> <p>Diagrams - Material for MkDocs</p> <pre><code>graph LR\n  A[Start] --&gt; B{Error?};\n  B --&gt;|Yes| C[Hmm...];\n  C --&gt; D[Debug];\n  D --&gt; B;\n  B ----&gt;|No| E[Yay!];</code></pre> <p>UML Sequence Diagrams</p> <pre><code>sequenceDiagram\n  Alice-&gt;&gt;John: Hello John, how are you?\n  loop Healthcheck\n      John-&gt;&gt;John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John--&gt;&gt;Alice: Great!\n  John-&gt;&gt;Bob: How about you?\n  Bob--&gt;&gt;John: Jolly good!</code></pre> <p>state transition diagrams</p> <pre><code>stateDiagram-v2\n  state fork_state &lt;&lt;fork&gt;&gt;\n    [*] --&gt; fork_state\n    fork_state --&gt; State2\n    fork_state --&gt; State3\n\n    state join_state &lt;&lt;join&gt;&gt;\n    State2 --&gt; join_state\n    State3 --&gt; join_state\n    join_state --&gt; State4\n    State4 --&gt; [*]</code></pre> <p>Class diagrams - not needed for Clojure</p> <p>Entity relationship diagrams are handy though</p> <pre><code>erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses</code></pre>"},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"<p>Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.</p> <ul> <li>1 <code>++1++</code> for numbers</li> <li>l <code>++\"l\"++</code> for lowercase character</li> <li>U <code>++u++</code> for uppercase character or <code>++\"U\"++</code> for consistency</li> </ul> <p>Punctionation keys use their name</p> <ul> <li>Space <code>++spc++</code></li> <li>, <code>++comma++</code></li> <li>Left <code>++arrow-left++</code></li> </ul> <p>For key sequences, place a space between each keyboard character</p> <ul> <li>Space g s <code>++spc++ ++\"g\"++ ++\"s\"++</code></li> </ul> <p>For key combinations, use join they key identifies with a <code>+</code></p> <ul> <li>Meta+X <code>++meta+x++</code></li> <li>Ctrl+Alt+Del <code>++ctrl+alt+del++</code></li> </ul> <p>MkDocs keyboard keys reference</p>"},{"location":"introduction/writing-tips/#images","title":"Images","text":"<p>Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers</p> SizeLazy LoadingAlignTheme SpecificAll Image Attributes <p><code>{style=\"height:150px;width:150px\"}</code> specifies the image size <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n</code></pre></p> <p></p> <p><code>{loading=lazy}</code> specifies an image should lazily load in the browser <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n</code></pre></p> <p><code>{aligh=left}</code> or <code>{aligh=right}</code> specifies the page alignment of an image. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n</code></pre></p> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p> <p><code>![Kitty Logo](image/kitty-light.png#only-dark)</code> or <code>![Kitty Logo](image/kitty-light.png#only-light)</code>  specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n</code></pre> Use the theme toggle in the top nav bar to see the icon change between light and dark.  </p> <p>Requires the color pallet toggle</p> <p>Alight right, lazy load and set image to 150x150</p> <pre><code>![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n</code></pre> <p>  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.</p>"},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"<p>Task lists</p> <ul> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit</li> <li> Vestibulum convallis sit amet nisi a tincidunt<ul> <li> In hac habitasse platea dictumst</li> <li> In scelerisque nibh non dolor mollis congue sed et metus</li> <li> Praesent sed risus massa</li> </ul> </li> <li> Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque</li> </ul> <p>Task List example</p> <pre><code>- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n</code></pre>"},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"<p>The humble tool tip</p> <p>Hover me</p> <p>with references</p> <p>Hover me</p> <p>Icon tool tip with a title</p> <p></p>"},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"<p>The HTML specification is maintained by the W3C.</p> <p>[HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium</p>"},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"<p>MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.</p> <p>Email Practicalli</p> <p>Practicalli Neovim</p>"},{"location":"introduction/concepts/","title":"Clojure concepts","text":"<p>Clojure is an elegant language for a more civilized development experience.</p> <p>Clojure supports the creation of simple software systems using immutable values and encouraging a pragmatic approach to pure functional design.</p> <p>A simple syntax means Clojure is quick to learn and a wide range of open source libraries provides a rapid way to build any kind of software. Designed as a hosted language, Clojure runs on many platforms including the Java Virtual Machine, GraalVM, Microsoft.Net, JavaScript engines.  Simple host language interoperability provides access to libraries from a wide range of programming languages, further extending the reach of Clojure.</p> <p>Experiment with the Clojure language to help understand concepts</p> <p>Spend some time eevaluating code in the REPL and then revisit this section to get a deeper understanding of the design and philosophy of the Clojure approach to functional programming.</p> <p>Clojure concepts are easier to relate to whist practicing with Clojure and building Clojure software solutions.</p>"},{"location":"introduction/concepts/#ten-big-ideas-plus-one","title":"Ten Big Ideas plus one","text":"<p>The key to understanding Clojure is ideas, not language constructs but the concepts that shape the language.</p> <p>Each of these ideas is valuable by itself, not only in Clojure. Taken together, however, they Begin to fill in the picture of why Clojure is changing the way many programmers think about software development.</p> <ol> <li>Extensible Data Notation</li> <li>Persistent Data Structures</li> <li>Sequences</li> <li>Transducers</li> <li>Specification</li> <li>Dynamic Development</li> <li>Async Programming</li> <li>Protocols</li> <li>ClojureScript</li> <li>Logic query / Logic Programming</li> <li>Atomic Succession Model</li> </ol> <p>Stuart Halloway presents Clojure in 10 big ideas (plus one) in the following video, also see presentation Content</p> <p> </p> <ul> <li>2013 RuPy slides</li> <li>2017 Chicago JUG slides</li> </ul>"},{"location":"introduction/concepts/#antithesis-of-clojure-and-simple-software-design","title":"Antithesis of Clojure and simple software design","text":"<p>In Narcissistic Design by Stuart Halloway, the antithesis of the Clojure view of software development is presented as a description of how unproductive and valueless much of the software industry has been in the past.</p> <p>Its essentially a guide on what to avoid if you are a responsible and professional software developer.</p> <p> </p>"},{"location":"introduction/concepts/all-bytecode-in-the-end/","title":"Its all Bytecode in the end","text":"<p>The REPL is your compiler</p> <p></p> <p>As soon as you evaluate your code in the REPL it is also being compiled in the background into Java Bytecode.  So there is no need for a separate build and run phase.</p> <p>Injecting code into the running environment provides the means for fast iterative development of code.</p>"},{"location":"introduction/concepts/clojure-made-simple/","title":"Clojure from the Author","text":"<p>A series of important videos from Rich Hickey, the author of Clojure who spent over 2 years designing core of Clojure around the concept of simplicity.  Since then Rich has stewarded the continued design and development of Clojure, ensuring it stays true to is founding principles.</p> <p>You do not need to watch these videos to start coding in Clojure, but they are very useful to adopt the approach and design idioms that make Clojure a highly effective language for software development.</p>"},{"location":"introduction/concepts/clojure-made-simple/#expert-to-expert-rich-hickey-and-brian-beckman-inside-clojure","title":"Expert to Expert: Rich Hickey and Brian Beckman - Inside Clojure","text":"<p>Discussing some of the key characteristics of the Clojure language and why those decisions were taken</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#clojure-made-simple","title":"Clojure made simple","text":"<p>Covers the major problems with software development and the challenges most programming languages fail to tackle completely.</p> <p>Discusses a simple approach to software development and the big picture view of how Clojure solves these problems</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#simplicity-matters","title":"Simplicity Matters","text":"<p>!!! QUOTE Rich Hickey, Clojure Benevolent Dictator for Life     As we move forward we have to take what we already have and make that [software] do more, make it do things differently, make it do things better,  and as we try to take on manipulating software we are going to be challenged to understand it in order to make that happen.     And I'll contend that you will completely be dominated by complexity.  I don't care what processes you are using, I don't care how well you test or anything else.  Complexity will dominate what you do.</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#discussing-design","title":"Discussing Design","text":""},{"location":"introduction/concepts/clojure-made-simple/#the-value-of-values","title":"The value of values","text":"<p>Rich Hickey provides analysis of the changing way we think about values (not the philosophical kind) in light of the increasing complexity of information technology and the advent of Big Data</p> <p> </p> <p>Also see the related video: Database as a value by Rich Hickey</p> <p> </p>"},{"location":"introduction/concepts/clojure-made-simple/#understanding-clojure-as-a-programming-language","title":"Understanding Clojure as a programming language","text":""},{"location":"introduction/concepts/design/","title":"Clojure Design","text":"<p>Clojure leads to a very component based approach to development.  There are no huge and bloated frameworks in Clojure.  The core is very small.  Hundreds of focused libraries to use in collaboration.</p> <p>Boiled down to the most simplest structure, Clojure applications you write typically look like this:</p> <pre><code>;; define a namespace\n(ns name-space.name)\n\n;; define one or more immutable data structures - the fewer the better typically\n(def my-data-structure [[{}{}]])\n\n;; define behaviour that acts on data structures inside one or more functions\n(defn my-function [parameter]\n  (my-behaviour parameter))\n\n;; Call those functions to make your application do something\n(my-behaviour data)\n</code></pre> <p>Hint As functions always evaluate to a value, a function can be used as an argument to another function (or itself if you get recursive !!)</p>"},{"location":"introduction/concepts/design/#data-focused-design-maps-vectors","title":"Data focused design - Maps &amp; Vectors","text":"<p>Maps (hash-map) and vectors are two more built-in persistent data structures that are more commonly used to represent data within a Clojure application.</p> <p>A vector is similar to an array in that its an indexed collection and so has fast random access.  Vectors are a catch all data structure that can hold any type of information, including other data structures and function calls.</p> <p>A hash-map is an associative data structure with key value pairs.  The keys are most commonly represented with Clojure keywords, although keys can be strings, numbers, collections or functions so long as all the keys are unique.</p> <p>Hash-maps are a collection of key / value pairs that provide an easy way to reference data by keys.  Its common to use a Clojure <code>keyword</code> type as the keys as keywords are self-referential (they point to themselves).  Using keywords in a map means you can use a specific keyword as a function call on the map that returns its associated value.</p> <p>Some examples of using these data structures this are:</p> <pre><code>;; A map of maps of maps with occasional vectors\n\n{:star-wars {\n    :characters {\n      :jedi   [\"Luke Skywalker\"\n               \"Obiwan Kenobi\"]\n      :sith   [\"Darth Vader\"\n               \"Darth Sideous\"]\n      :droids [\"C3P0\"\n               \"R2D2\"]}\n    :ships {\n      :rebel-alliance  [\"Millennium Falcon\"\n                        \"X-wing fighter\"]\n      :imperial-empire [\"Intergalactic Cruiser\"\n                        \"Destroyer\"\n                        \"Im just making these up now\"]}}}\n</code></pre>"},{"location":"introduction/concepts/design/#hintbasic-design-principle","title":"Hint::Basic design principle","text":"<p>\u201cIt is better to have 100 functions operate on one data structure than 10 functions on 10 data structures.\u201d \u2014Alan Perlis</p>"},{"location":"introduction/concepts/design/#extensibility-via-macros","title":"Extensibility via Macros","text":"<p>You can extend the language and define your own constructs using Macros.</p> <p>The first example of this you see is from Leiningen.  The <code>defproject</code> function is a macro that helps you easily define the configuration of a Clojure project.</p> <p>An example of a macro that is part of the core Clojure language is <code>defn</code>.  When you define a function with <code>defn</code> it is syntactic sugar for defining a thing that is a function.</p> <pre><code>  (defn my-function [argument] (my-behaviour argument) )\n\n  (def my-function\n    (fn [argument] (my-behaviour argument)))\n</code></pre>"},{"location":"introduction/concepts/design/#special-forms-the-building-blocks-of-clojure","title":"Special forms - the building blocks of Clojure","text":"<p>The following are the building blocks of Clojure, everything else is either a macro or a function</p> <p>The Clojure / LISP special forms</p> <pre><code>def, do, if, let, loop, fn, quote, recur, set!, var\n</code></pre> <p>The forms added for Interoperability with the host platform (mainly Java / JVM)</p> <pre><code>monitor-enter, monitor-exit,\ncatch, dot ('.'), finally, new, throw, try\n</code></pre>"},{"location":"introduction/concepts/features/","title":"Features of Clojure","text":""},{"location":"introduction/concepts/features/#dynamic-language","title":"Dynamic language","text":"<p>A problem space can quickly be explored through code to test your assumptions.  The design of code is easy to change as you are not managing type changes, Clojure is very good at managing data that would otherwise lead to exceptions.</p> <p>As a dynamic language the code is quite terse and developers are encouraged to write very modular code, therefore it is easy to refactor.</p>"},{"location":"introduction/concepts/features/#dynamic-development-repl","title":"Dynamic Development - REPL","text":"<p>Clojure has a REPL (Read Evaluate Print Loop), this is the Clojure run-time environment.  You can define functions and data structures, then evaluate them to run either all your code or just a single expression.  You can even change code and re-evaluate it whilst your application is still running and immediately see the effect that change has.</p> <p>So the REPL is a very fast way to explore your problem domain with code</p> <p>You could even connect to the REPL of a live system and change its behaviour without any down time (unless of course you write code that crashes).</p>"},{"location":"introduction/concepts/features/#pure-functional-programming","title":"'Pure' Functional Programming","text":"<p>Functions return a value (even if that value is nil) and you can therefore use a function as an argument to another function.  This is termed as first order functions.</p> <p>Clojure encourages a relatively pure approach to functional programming and Clojure can be considered immutable by default</p>"},{"location":"introduction/concepts/features/#immutability","title":"Immutability","text":"<ul> <li>immutable data structures at its core, everything is immutable by default</li> <li>in imperative programming, we change state where ever we like</li> <li>in functional programming we avoid changing state as much as possible</li> <li>if a function does not change state it is referentially transparent, always returning the same result when given the same input (arguments) - often returned as a pure function</li> <li>impure functions can affect other functions and therefore has to be very mindful of the changes it makes and when it makes them</li> <li>pure functions are truly modular as they do not affect any other part of the system</li> </ul>"},{"location":"introduction/concepts/features/#persistent-data-structures","title":"Persistent Data Structures","text":"<p>List, Map, Vector and Set are all built in data structures that are immutable.</p> <p>If you run a function that seems to change a data structure, its actually returning a new data structure.  Via a shared-memory model, new data structures are created cheaply as they share the common data elements from the original data structure and only include additional elements.</p>"},{"location":"introduction/concepts/features/#homoiconicity","title":"Homoiconicity","text":"<p>One thing that keeps Clojure a small language is the fact that the same syntax is used to represent data and behaviour.  For example, a function call is defined using a list, data structures and functions are defined using a list.  In fact everything is a list, although we use a little syntactic sugar here and there to make the code quicker for a human to parse.</p>"},{"location":"introduction/concepts/features/#clojure-is-an-implementation-of-lisp","title":"Clojure is an implementation of Lisp","text":"<p>Lisp stands for LISt Processing, so its no surprise that all Clojure code is defined in a list.</p> <p>The open Parenthesis <code>(</code> denotes the start of a list, the first element of that list is evaluated as a function call, everything else in the list is data.</p> <p>The evaluation of the first element of a list can be behaviour of <code>(</code> can be over-ridden using <code>quote</code> or its short form the quote character, ', so the list elements are all treated as data.</p>"},{"location":"introduction/concepts/features/#runtime-polymorphism","title":"Runtime Polymorphism","text":"<p>See Clojure arity and multi-methods for more information</p>"},{"location":"introduction/concepts/features/#concurrent-programming-parallelism","title":"Concurrent Programming &amp; Parallelism","text":"<p>Concurrent code is much safer when you data does not change state (eg. immutable values).  Clojure encourages an immutable approach with its built in persistent data structures (list, Map, Vector, Set).  Using Pure Functions that are not affected by or cause side effects also make writing concurrent code trivial.</p> <p>Clojure helps you scale your applications by with a parallel processing approach, as you can run functions over immutable data-structures without conflict.</p>"},{"location":"introduction/concepts/features/#hosted-on-the-jvm","title":"Hosted on the JVM","text":"<p>Clojure is compiled to bytecode that runs on the Java Virtual Machine.  This helps Clojure run at a very high performance (close to Java, C++, etc.)</p> <p>Clojure has a concise and easy to use Java Interoperability, enabling you to use any libraries that run on the JVM (Java, Groovy, Scala, Jruby, Jython, etc).</p> <ul> <li>many parts of the Clojure standard library, Clojure.core defer to the Java Standard library, for example for I/O (reading,writing files)</li> <li>Clojure makes invoking Java very convenient and provides special primitive constructs in the Clojure language to do so (new .javaMethodName javaClassName. etc)</li> </ul> <p>ClojureScript generated JavaScript that will run in a browser.  ClojureCLR will compile to bytecode that runs on the Microsoft .Net platform.</p>"},{"location":"introduction/concepts/features/#managed-state-changes","title":"Managed State Changes","text":"<p>Using <code>atoms</code> or <code>refs</code> in clojure you can have mutable data.  Changes are done safely within Software Transactional Memory (STM), like having an in-memory ACID database managing access</p>"},{"location":"introduction/concepts/features/#extend-the-language-with-macros","title":"Extend the language with Macros","text":"<p>Clojure uses macros</p> <p>Fixme Review the following content to see if its relevant ?</p> <p>** Input &amp; output with functional programming</p> <ul> <li>other fp languages like haskel &amp; Scala use monads to encapsulate data changes whilst appearing stateless to the rest of the program - monads allow us to sneak in impure code into the context of pure code.</li> <li>Clojure doesn't try and enforce functional purity, so any function can include impure code</li> <li>most functions should be pure though or you loose the benefits of functional programming</li> <li>Clojure encourages minimal state changes / mutable state - so its up to the developer to keep the ratio of mutable data small</li> <li> <p>Clojure uses reference types to manage threads and mutable state.  References provide synchronisation of threads without using locks (notoriously cumbersome).  See STM</p> </li> <li> <p>Supporting concurrency</p> </li> <li> <p>atoms etc</p> </li> <li>automatic management of state changes via Software transactional memory - like having an ACID database in memory, managing requests to change values over time.</li> <li> <p>by having immutable data structures - if your values do not change then its trivial to have massive parallelism.</p> </li> <li> <p>A modern LISP</p> </li> <li> <p>leaner syntax and not as many brackets as LISP</p> </li> <li>clean data structure syntax at the core of the language</li> <li>LiSP was the first language to introduce first class functions, garbage collection and dynamic typing, which are common in languages used today</li> </ul> <p>Macros</p> <ul> <li>a function that takes in source code and returns source code, replacing the macro code</li> <li>use macros to take out repetition / boilerplate code</li> <li>as LISP syntax is extremely simple it is much easier to write macros that work compared to non-LISP languages</li> </ul> <p>Clojure emphasizes safety in its type system and approach to parallelism, making it easier to write correct multi-threaded programs.</p> <p>Clojure is very concise, requiring very little code to express complex operations.</p> <p>Data centric design - a well constructed data structure helps define and clarify the purpose of the code</p> <p>Modularity - Clojure and its community build things in modules / components that work together (in a similar design approach to the Unix file system, for example).</p> <p>It offers a REPL and dynamic type system: ideal for beginners to experiment with, and well-suited for manipulating complex data structures.</p> <p>A consistently designed standard library and full-featured set of core data types rounds out the Clojure toolbox.</p> <p>Clojure is close to the speed of Java</p>"},{"location":"introduction/concepts/features/#constraints","title":"Constraints","text":"<p>Clojure relies on the JVM so there can be a longer boot time than a scripting language like Javascript.  However, as you can connect to the Clojure runtime (the REPL) of a live system and because Clojure is dynamic, you can make changes to that live system without any downtime.</p> <p>If you require more performance from Clojure, you can specify ahead of time compilation.</p>"},{"location":"introduction/concepts/functional-reactive-programming/","title":"Functional Reactive Programming","text":"<p>Functional Reactive programming is used in ClojureScript with libraries including reagent, re-frame, rum, etc.</p> <p>Functional Reactive Programming is an elegant means of modeling state over time in an easily composable way. Approaching the problem conceptually and developing a formal semantics first can lead to better optimization potential and simpler implementation.</p> <p>Taking a functional reactive programming approach results in systems that are:</p> <ul> <li>Easier to reason about</li> <li>Simpler to implement</li> <li>Easier to optimize</li> </ul> <p>Functional Reactive Programming (FRP) is a specific formalism of a model of behaviors that change in response to events, created by Conal Elliot. That's a pretty abstract statement, but FRP is abstract itself. It does not denote a particular implementation, but rather a formal semantics. It is not a style of programming or a paradigm. It's simply a formalism.</p> <p>Functional Reactive Programming (and Denotational Design, also by Conal Elliott) has a lot to teach us about how to design functional programs.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#conal-elliott-on-frp-audio-interview","title":"Conal Elliott on FRP Audio Interview","text":"<p>If you're looking for an explanation of the Functional Reactive Programming from the man who invented it, along with an idea of the intriguing process he used to invent it, this HaskellCast episode is for you.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#functional-reactive-animation","title":"Functional Reactive Animation","text":"<p>A great paper from 1997 that spells out an early form of Functional Reactive Programming. It specifies behaviors (functions of time to a value) that change when events occur.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#conal-elliots-home-page","title":"Conal Elliot's home page","text":"<p>Conal Elliot created FRP while he was researching graphics and animation. Be sure to check out his FRP papers section.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#push-pull-functional-reactive-programming","title":"Push-pull functional reactive programming","text":"<p>A more advanced formulation of Functional Reactive Programming that formalizes the types and operations using Haskell's common type classes (Functor, ApplicativeFunctor, Monoid, etc). This one also includes a video of the paper presentation given at ICFP.</p> <p>The main breakthrough of this paper is to model the notion of a future value for events that have not yet happened. But if they have not happened, how can future values be compared? For instance, how does one ask if event a happens before event b if neither of them has happened yet? The paper develops a cool and inspiring formalism which resolves this problem. And one is left with a value that represents the entire behavior of a system past, present, and future.</p>"},{"location":"introduction/concepts/functional-reactive-programming/#elm-thesis-pdf","title":"Elm Thesis - PDF","text":"<p>Elm is a different take on FRP (and it is potentially not FRP, according to some). Instead of behaviors (functions of time to a value), Elm uses discreet signals which are transformed to other signals using functional map-like operations. It also solves a real issue with computationally expensive operations blocking the propagation of signals by making some signals asynchronous.</p> <p>All-in-all, the thesis is a pleasure to read. It is very clear and a decent introduction to the myriad implementations of FRP out there. See the bibliography.</p>"},{"location":"introduction/concepts/misc/","title":"Misc","text":""},{"location":"introduction/concepts/misc/#characteristics","title":"Characteristics","text":"<ul> <li>Dynamic</li> <li>typed - like Python, Ruby or Groovy</li> <li>because its a LISP - you can redefine running code by redefining functions and re-evaluating</li> <li> <p>REPL - a fast way to explore your problem domain with code</p> </li> <li> <p>Functional programming</p> </li> <li>in contrast to imperative programing</li> <li>immutable data structures at its core, everything is immutable by default</li> <li>if any piece of data can be changed, that is mutable state</li> <li>in imperative programming, we change state where ever we like</li> <li>in functional programming we avoid changing state as much as possible</li> <li>if a function does not change state it is referentially transparent, always returning the same result when given the same input (arguments) - often returned as a pure function</li> <li>impure functions can affect other functions and therefore has to be very mindful of the changes it makes and when it makes them</li> <li>pure functions are truly modular as they do not affect any other part of the system ** Changing state</li> <li>rather than changing a data structure, fp instead creates a new data structure that contains the changes and copies of the existing data.</li> <li>to manage the potential overhead of copying data structures, Clojure uses Persistent collections (Lists, Vectors, Maps) which are immutable but provide an efficient way to mutate by sharing common elements (data) ** Input &amp; output with functional programming</li> <li>other fp languages like haskel &amp; Scala use monads to encapsulate data changes whilst appearing stateless to the rest of the program - monads allow us to sneak in impure code into the context of pure code.</li> <li>Clojure doesn't try and enforce functional purity, so any function can include impure code</li> <li>most functions should be pure though or you loose the benefits of functional programming</li> <li>Clojure encourages minimal state changes / mutable state - so its up to the developer to keep the ratio of mutable data small</li> <li> <p>Clojure uses reference types to manage threads and mutable state.  References provide synchronisation of threads without using locks (notoriously cumbersome).  See STM</p> </li> <li> <p>Hosted on the Java Virtual Machine</p> </li> <li>written for the JVM &amp; heavily integrated, giving beautiful integration</li> <li>Clojure is compiled to Java byte code</li> <li>many parts of the Clojure standard library, Clojure.core defer to the Java Standard library, for example for I/O (reading,writing files)</li> <li> <p>Clojure makes invoking Java very convenient and provides special primitive constructs in the Clojure language to do so (new .javaMethodName javaClassName. etc)</p> </li> <li> <p>Supporting concurrency</p> </li> <li>atoms etc</li> <li>automatic management of state changes via Software transactional memory - like having an ACID database in memory, managing requests to change values over time.</li> <li> <p>by having immutable data structures - if your values do not change then its trivial to have massive parallelism.</p> </li> <li> <p>A modern LISP</p> </li> <li>leaner syntax and not as many brackets as LISP</li> <li>clean data structure syntax at the core of the language</li> <li>LiSP was the first language to introduce first class functions, garbage collection and dynamic typing, which are common in languages used today</li> </ul> <p>Macros</p> <ul> <li>a function that takes in source code and returns source code, replacing the macro code</li> <li>use macros to take out repetition / boilerplate code</li> <li>as LISP syntax is extremely simple it is much easier to write macros that work compared to non-LISP languages</li> </ul> <p>fixme assuming you need more, I'll add to this page, but Clojure is a very powerful language, incredibly flexible and tonnes of fun.  What more do you need ?</p> <p>fixme concepts to explore</p> <p>Clojure emphasizes safety in its type system and approach to parallelism, making it easier to write correct multi-threaded programs.</p> <p>Clojure is very concise, requiring very little code to express complex operations.</p> <p>Data centric design - a well constructed data structure helps define and clarify the purpose of the code</p> <p>Modularity - Clojure and its community build things in modules / components that work together (in a similar design approach to the Unix file system, for example).</p> <p>It offers a REPL and dynamic type system: ideal for beginners to experiment with, and well-suited for manipulating complex data structures.</p> <p>A consistently designed standard library and full-featured set of core data types rounds out the Clojure toolbox.</p> <p>Clojure is close to the speed of Java</p>"},{"location":"introduction/concepts/misc/#constraints","title":"Constraints","text":"<p>Clojure relies on the JVM so there can be a longer boot time than a scripting language like Javascript.  However, as you can connect to the Clojure runtime (the REPL) of a live system and because Clojure is dynamic, you can make changes to that live system without any downtime.</p> <p>If you require more performance from Clojure, you can specify ahead of time compilation.</p>"},{"location":"introduction/concepts/naming-local/","title":"Naming - local scope","text":""},{"location":"introduction/concepts/naming-local/#local-names-in-functions","title":"Local names in functions","text":"<p>You can define names for things within the scope of a function using the <code>let</code> function.</p>"},{"location":"introduction/concepts/naming-local/#example","title":"Example","text":"<p>You can use the let function to define a simple expression, for which everything will go out of scope once it has been evaluated</p> <pre><code>(let [local-name \"some value\"])\n(let [minutes-in-a-day (* 60 60 24)])\n</code></pre> <p>You can also use <code>let</code> inside a function to do something with the arguments passed to that function.  Here we calculate the hourly-rate from a yearly salary, returning the calculated-rate.</p> <p>(defn hourly-rate [yearly-salary weeks-in-year days-in-week]   (let [calculated-rate (/ yearly-salary weeks-in-year days-in-week)]     calculated-rate))</p> <p>(hourly-rate 60000 48 5)</p> <pre><code>## Local names in data structures\n\n  When defining a map you are creating a series of key value pairs.  The key is essentially a name that represents the value it is paired with.  Keys are often defined using a `:keyword`.\n\n```clojure\n  {:radius 10, :pi 22/7 :colour purple}\n\n  (def my-circle {:radius 10, :pi 22/7 :colour purple})\n</code></pre> <p>Fixme This is incorrect, as a Clojure keyword type (a name starting with :) have global scope within a namespace.  If the keys were strings, then they would have the scope of just the collection.</p>"},{"location":"introduction/concepts/naming-things/","title":"Naming things - data structures and functions","text":"<p>The <code>def</code> function is used to name data structures in Clojure.</p> <p>You can also use <code>def</code> to name functions, however it is more common to use <code>defn</code> (which is a macro around def) to give a function a name.</p>"},{"location":"introduction/concepts/naming-things/#keeping-things-private","title":"Keeping things private","text":"<p>There is less emphasis on keeping functions and data structures private (compared to Java, C++, C#).  If you want to define a function name so that it is only accessible by other functions of the same namespace, you can use the <code>defn-</code> function.</p> <p>There is no private equivalent for <code>def</code> (as of Clojure 1.6) however you can use metadata to specify this</p> <p>(def ^:private name data)</p> <p>TODO: check if there is anything new around this or other common practices</p>"},{"location":"introduction/concepts/naming-things/#misc-writing-a-private-def-macro","title":"Misc - writing a private def macro","text":"<p>You could write your own macro to create a private <code>def</code> called <code>def-</code></p> <pre><code>(defmacro def- [item value]\n  `(def ^{:private true} ~item ~value)\n)\n</code></pre> <p>There are no naming conventions for a private symbol name.  As its defined an used within the scope of that one namespace (file), then there is no real need to make a special convention.  Private functions will just be called as normal within the namespace and it will be quite clear from the function definition that it is private.</p> <p>Clojure community style guide</p>"},{"location":"introduction/concepts/naming-things/#example","title":"example","text":"<p>Learning Clojure #4: private functions http://tech.puredanger.com/2010/02/09/clojure-4-private-functions/</p> <p>Sometimes in a Clojure file you just want some helper functions that shouldn\u2019t be exposed outside the namespace. You can create a private function using the special defn- macro instead of defn.</p> <p>For instance, create a file foo/bar.clj with a public and a private function:</p> <p>(ns foo.bar) (defn- sq [x] (* x x)) (defn sum-squares [a b] (+ (sq a) (sq b)))</p> <p>Then use it from the REPL:</p> <p>user=&gt; (use 'foo.bar) nil user=&gt; (sum-squares 3 4) 25 user=&gt; (sq 5) java.lang.Exception: Unable to resolve symbol: sq in this context (NO_SOURCE_FILE:6)</p>"},{"location":"introduction/concepts/purpose/","title":"When to use Clojure","text":"<p>Clojure is a general purpose language suitable for any kind of application or service.  As Clojure implementations run across multiple technology platforms and operating systems, there are very few barriers to its use.</p> <p>So Clojure is great for webapps, data science, big data, finance industry (banking, trading, insurance, etc), devops tools (log analysis, etc) and anything else really.</p> <p>There are areas where Clojure obviously excels.</p>"},{"location":"introduction/concepts/purpose/#effective-data-manipulation","title":"Effective Data Manipulation","text":"<p>Fundamentally all software systems take in data (in the form of values or events), process or react to that data and return as a result.</p> <p>The persistent data structures in Clojure (list, vector, hash-map and set) provide an efficient way to use immutable collections of data.</p> <p>The <code>clojure.core</code> library contains a vast number of data processing functions in Clojure so data is easily transformed</p>"},{"location":"introduction/concepts/purpose/#highly-scalable","title":"Highly Scalable","text":"<p>Clojure code is encouraged to be immutable and functions to be pure, you can run millions of parallel instances of your application or service for massive processing power.  These features also vastly simplify concurrent programming.</p>"},{"location":"introduction/concepts/purpose/#reducing-complexity","title":"Reducing Complexity","text":"<p>Clojure encourages a component design through functional composition, breaking down problems into components</p> <p>Clojure and its libraries are all great examples of well designed components and the community strongly encourages this approach.</p>"},{"location":"introduction/concepts/purpose/#hintfunctional-reactive-programming","title":"Hint::Functional Reactive Programming","text":"<p>You can also use ClojureScript for Functional Reactive programming of client-side apps for browsers and mobile device.</p>"},{"location":"introduction/concepts/rationale/","title":"The rationale for Clojure","text":"<p>At the time Clojure was created there were no LISP based languages that ran on a widely adopted platform, that also made concurrency easier for the developer to manage.</p> <p>Developers and the companies that hire them are comfortable with the performance, security and stability of the Java Virtual Machine.</p> <p>While Java developers may envy the succinctness, flexibility and productivity of dynamic languages, they have concerns about running on customer-approved infrastructure, access to their existing code base and libraries, and performance. In addition, they face ongoing problems dealing with concurrency using native threads and locking. Clojure is an effort in pragmatic dynamic language design in this context. It endeavors to be a general-purpose language suitable in those areas where Java is suitable. It reflects the reality that, for the concurrent programming future, pervasive, uncontrolled mutation simply has to go.</p> <p>Clojure meets its goals by: embracing an industry-standard, open platform - the JVM; modernizing a venerable language - Lisp; fostering functional programming with immutable persistent data structures; and providing built-in concurrency support via software transactional memory and asynchronous agents. The result is robust, practical, and fast.</p> <p>Clojure has a distinctive approach to state and identity.</p> <p>Why Clojure?</p>"},{"location":"introduction/concepts/rationale/#motivating-ideas-behind-clojure","title":"Motivating ideas behind Clojure","text":"<p>A LISP base language design is very effecitve</p> <ul> <li> <p>Lambda calculus yields an extremely small core with very little syntax required</p> </li> <li> <p>Core advantage still code-as-data and syntactic abstraction</p> </li> </ul> <p>Standard Lisps (Common Lisp, Scheme) have not evolved over time, since standardisation.  Their core data structures are mutable and not extensible and therefore no mechanisms for effectively dealing with concurrency.</p> <p>Clojure is a Lisp not constrained by backwards compatibility, allowing modernisation of the language that otherwise deters developers from adoption.</p> <p>Clojure extends the code-as-data paradigm to maps and vectors</p> <p>All data structures default to immutability</p> <p>Core data structures are extensible abstractions</p> <p>Embraces a platform (JVM)</p> <p>Functional programming is a good thing</p> <ul> <li>Immutable data + first-class functions</li> <li>Could always be done in Lisp, by discipline/convention</li> </ul> <p>But if a data structure can be mutated, dangerous to presume it won't be In traditional Lisp, only the list data structure is structurally recursive Pure functional languages tend to strongly static types Not for everyone, or every task Clojure is a functional language with a dynamic emphasis All data structures immutable &amp; persistent, supporting recursion Heterogeneous collections, return types Dynamic polymorphism Languages and Platforms VMs, not OSes, are the platforms of the future, providing: Type system Dynamic enforcement and safety Libraries Abstract away OSes Huge set of facilities Built-in and 3rd-party Memory and other resource management GC is platform, not language, facility Bytecode + JIT compilation Abstracts away hardware Language as platform vs. language + platform Old way - each language defines its own runtime GC, bytecode, type system, libraries etc New way (JVM, .Net) Common runtime independent of language Language built for platform vs language ported-to platform Many new languages still take 'Language as platform' approach When ported, have platform-on-platform issues Memory management, type-system, threading issues Library duplication If original language based on C, some extension libraries written in C don't come over Platforms are dictated by clients 'Must run on JVM' or .Net vs 'must run on Unix' or Windows JVM has established track record and trust level Now also open source Interop with other code required C linkage insufficient these days Java/JVM is a language and platform Not the original story, but other languages for JVM always existed, now embraced by Sun Java can be tedious, insufficiently expressive Lack of first-class functions, no type inference, etc Ability to call/consume Java is critical Clojure is the language, JVM the platform Object Orientation is overrated Born of simulation, now used for everything, even when inappropriate Encouraged by Java/C# in all situations, due to their lack of (idiomatic) support for anything else Mutable stateful objects are the new spaghetti code Hard to understand, test, reason about Concurrency disaster Inheritance is not the only way to do polymorphism \"It is better to have 100 functions operate on one data structure than to have 10 functions operate on 10 data structures.\" - Alan J. Perlis Clojure models its data structures as immutable objects represented by interfaces, and otherwise does not offer its own class system. Many functions defined on few primary data structures (seq, map, vector, set). Write Java in Java, consume and extend Java from Clojure. Polymorphism is a good thing Switch statements, structural matching etc yield brittle systems Polymorphism yields extensible, flexible systems Clojure multi-methods decouple polymorphism from OO and types Supports multiple taxonomies Dispatches via static, dynamic or external properties, metadata, etc Concurrency and the multi-core future Immutability makes much of the problem go away Share freely between threads But changing state a reality for simulations and for in-program proxies to the outside world Locking is too hard to get right over and over again Clojure's software transactional memory and agent systems do the hard part</p> <p>In short, I think Clojure occupies a unique niche as a functional Lisp for the JVM with strong concurrency support. Check out some of the features.</p>"},{"location":"introduction/concepts/what-is-functional-programming/","title":"What is Functional Programming","text":"<p>Functional programming can seem quite different from imperative programming used in languages like C, C++ and Java.</p> <p>Imperative languages may seem easier initially, as defining one step after another is familiar approach to many things in live.  As the scale of a system grows, so does complexity.  Imperative languages applied object oriented design to manage complexity with varied rates of success.</p> <p>When shared mutable state is common in an OO design, then a system quickly becomes complex and very difficult to reason about.</p> <p>Functional programming is actually simpler that the OO approach, although initially it may be unfamiliar and not considered as easy.  As systems grow in complexity, the building blocks are still simple and deterministic, creating a system that is far easier to reason about.</p>"},{"location":"introduction/concepts/what-is-functional-programming/#imperative-programming-languages","title":"Imperative programming languages","text":"<p>In Imperative languages code is written that specifies a sequential of instructions that complete a task.  These instructions typically modifies program state until the desired result is achieved.</p> <p>Variables typically represent memory addresses that are mutable (can be changed) by default.</p> <p></p>"},{"location":"introduction/concepts/what-is-functional-programming/#functional-programming-languages","title":"Functional programming languages","text":"<p>Individual tasks are small and achieved by passing data to a function which returns a result.</p> <p>Functions are composed together to form more complex tasks and satisfy larger business logic.  These composed functions pass the result of their evaluation to the next function, until all functions in the composition have been evaluated.</p> <p>The entire functional program can be thought of as a single function defined in terms of smaller ones.</p> <p>Program execution is an evaluation of expressions, with the nesting structure of function composition determining program flow.</p> <p>Data is immutable and cannot be change once created.  Changes are expressed as new values, with complex values sharing common values for efficiency.</p> <p></p>"},{"location":"iterate-over-data/","title":"Iterate over data","text":"<p>Clojure data is typically within one or more of the built in collection types (vector, map, list, set).</p> <p>We can use some functions in Clojure core directly on these collection types.  Other clojure core functions need a little help.</p>"},{"location":"iterate-over-data/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/#map","title":"map","text":"<p>Used to create a new collection by applying a given function to each element of the collection in turn.</p> <pre><code>(map inc [1 2 3])\n</code></pre> <p>If there are multiple collections, map returns a new collection with values created by calling the function with a value from each of the collections.  Once map reaches the end of one collection it stops and returns the result.</p> <pre><code>(map + [1 2 3] [4 5 6] [7 8 9])\n</code></pre>"},{"location":"iterate-over-data/#apply","title":"apply","text":"<p>Used to remove all the values from a collection so they are treated as individual arguments to the function given to apply.</p> <pre><code>(= (apply + [1 2 3])\n   (+ 1 2 3))\n</code></pre>"},{"location":"iterate-over-data/#reduce","title":"reduce","text":"<p>reduce can be used in a similar way as apply, to transform a collection into a different value.</p> <p>reduce can also take an argument referred to as an accumulator, used to keep local state as reduce iterates through the values in the collection.</p> <p>A function used with reduce is called a reducing function and is a more abstract approach to loop/recur although its possible to give your reducing function a name so is more reusable.</p>"},{"location":"iterate-over-data/#threading-macros","title":"threading macros","text":"<p>Write code that reads as a sequential series of function calls, rather that the nested function calls typical in lisp.</p> <p>A threading macro is often used to thread a collection through a number of function calls and expressions.</p>"},{"location":"iterate-over-data/#comp","title":"comp","text":"<p>Compose functions together that work over a collection.  It can be seen as a more abstract approach to a threading macro or nested function calls.</p>"},{"location":"iterate-over-data/#transduce","title":"transduce","text":"<p>Used like comp to create a pipeline of function calls, however, each function call or expression must return a transducer (transforming reduction).  Many <code>clojure.core</code> functions return a transducer if you do not provide the collection argument.</p>"},{"location":"iterate-over-data/apply/","title":"apply","text":""},{"location":"iterate-over-data/apply/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/comp/","title":"comp - composing functions","text":""},{"location":"iterate-over-data/comp/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/filter-remove/","title":"filter and remove","text":"<p>Use filter and remove with predicate functions, those returning true or false, to create a sub-set of the data.</p> <p>filter creates a new collection that contains all the matching values from the predicate function (true).</p> <p><code>remove</code> creates a new collection with contains all the values that didn't match the predicate function (false).</p> <pre><code>(filter odd? [1 2 3 4 5 6 7 8 9])\n</code></pre>"},{"location":"iterate-over-data/filter-remove/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map-fn/","title":"map with fn - anonymous function","text":"<pre><code>(map (fn [arg] (+ arg 5)) [1 2 3 4 5])\n</code></pre> <p>There is a syntactic short-cut for the anonymous function that does not require a name for the arguments</p> <p><code>#(+ %1 5)</code></p> <p>Adding this into our previous expression we can see that its still quite readable and helps keep the code clean.</p> <pre><code>(map #(+ arg 5) [1 2 3 4 5])\n</code></pre>"},{"location":"iterate-over-data/map-fn/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map-fn/#hintanonymous-function-name","title":"Hint::Anonymous function name","text":"<p>Anonymous functions do not have an externally referable name, so must be used in-line with an expression.</p> <p>The <code>fn</code> function can be defined with a name, however, this is only available in the scope of that function definition, the name cannot be used to refer to that function outside of its definition.</p> <p>Including a name within a <code>fn</code> definition enables the function to call itself, therefore creating an anonymous recursive function.</p>"},{"location":"iterate-over-data/map-partial/","title":"map with partial","text":""},{"location":"iterate-over-data/map-partial/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/map/","title":"map function","text":""},{"location":"iterate-over-data/map/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>Add examples of using the map function with data</p>"},{"location":"iterate-over-data/reduce/","title":"reduce","text":""},{"location":"iterate-over-data/reduce/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"iterate-over-data/transduce/","title":"transduce and transforming reducers","text":""},{"location":"iterate-over-data/transduce/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":""},{"location":"libraries/","title":"Libraries","text":""},{"location":"libraries/clojars/","title":"Clojars","text":""},{"location":"libraries/clojure-core-lisp-comprehension/","title":"Libraries: <code>clojure.core</code> lisp comprehension","text":""},{"location":"libraries/clojure-core-lisp-comprehension/#todowork-in-progress-sorry","title":"TODO::work in progress, sorry","text":"<p>discuss functions for list comprehension <code>for</code></p>"},{"location":"libraries/clojure-core/","title":"Understanding Clojure Libraries: <code>clojure.core</code>","text":""},{"location":"libraries/clojure-core/#warningvery-rough-draft-of-an-idea","title":"Warning::Very rough draft of an idea","text":"<p>Experimenting with the value of grouping functions in clojure.core to help ensure you are exposed to most of the concepts in Clojure</p>"},{"location":"libraries/clojure-core/#families-of-functions","title":"Families of functions","text":"<ul> <li>List Comprehension (for, while, )</li> <li> <p>used to process multiple collections</p> </li> <li> <p>Transformations (map, filter, apply, reduce )</p> </li> <li>transform the contents of a collection</li> </ul>"},{"location":"libraries/edn/","title":"edn","text":""},{"location":"libraries/om/","title":"om","text":""},{"location":"modifying-data-structures/","title":"Modifying data structures","text":"<p>Wait, I thought you said that data structures were immutable!  So how can we change them then?</p> <p>Yes, lists, vectors, maps and sets are all immutable.  However, you can get a new data structure that has the changes you want. To make this approach efficient, the new data structure contains only the new data and links back to the existing data structure for shared data elements.</p> <p>We will see some of the most common functions that work with data structures in this section.  In actuality, everything can be considered a function that works on a data structure though, as that is the language design of clojure.</p>"},{"location":"modifying-data-structures/lists/","title":"Lists","text":"<p>You can change lists with the <code>cons</code> function, see <code>(doc cons)</code> for details</p> <p>(cons 5 '(1 2 3 4))</p> <p>You will see that <code>cons</code> does not change the existing list, it create a new list that contains the number 5 and a link to all the elements of the existing list.</p> <p>You can also use cons on vectors <code>(cons 5 [1 2 3 4])</code></p> <pre><code>(cons \"fish\" '(\"and\" \"chips\"))\n\n(conj '(1 2 3 4) 5)\n\n(conj [1 2 3 4] 5)\n\n\n;; Lets define a simple list and give it a name\n(def list-one '(1 2 3))\n\n;; the name evaluates to what we expect\nlist-one\n\n;; If we add the number 4 using the cons function, then we\n;; get a new list in return, with 4 added to the front (because thats how lists work with cons)\n(cons 4 list-one)\n\n;; If we want to keep the result of adding to the list, we can assign it a different name\n(def list-two (cons 4 list-one))\n;; and we get the result we want\nlist-two\n\n;; we can also pass the original name we used for the list to the new list\n(def list-one (cons 4 list-one))\n\n;; If we re-evaluate the definition above, then each time we will get an extra\n;; number 4 added to the list.\n\nlist-one\n\n;; Again, this is not changing the original list, we have just moved the name\n;; of the list to point to the new list.\n;; Any other function working with this data structure before reassigning the name\n;; will not be affected by the re-assignment and will use the unchanged list.\n</code></pre>"},{"location":"modifying-data-structures/maps/","title":"Maps","text":"<p>The <code>conj</code> function works on all of the Clojure collections.  The map collection also has functions that affect the evaluation of a map and the value of map returned.</p>"},{"location":"modifying-data-structures/maps/#adding-new-values-with-conj","title":"Adding new values with <code>conj</code>","text":"<p>If you have a collection of maps, you can add another map to that collection with the <code>conj</code> function.</p> <pre><code>(conj [{:map1 1}] {:map2 2})\n\n;; =&gt; [{:map1 1} {:map2 2}]\n</code></pre>"},{"location":"modifying-data-structures/maps/#changing-values-with-assoc","title":"Changing values with <code>assoc</code>","text":"<p>The <code>assoc</code> function is used to update a value in a map without necessary being concerned about the current value.  <code>assoc</code> returns a complete new map with the specified value.</p> <pre><code>(assoc {:food \"Fish\"} :food \"Fish&amp;Chips\")\n\n;; =&gt; {:food \"Fish&amp;Chips\"}\n</code></pre> <p>It does not matter how many keys are in the map, as keys are unique, then <code>assoc</code> will look up the specific key and change its value to that specified in the third argument.</p> <p>If a key is not in the map, <code>assoc</code> will add both the key and the value.</p> <pre><code>(def alphabet-soup {:a 1 :b 2 :c 3})\n\n(assoc alphabet-soup :d 4)\n\n;; =&gt; {:a 1, :b 2, :c 3, :d 4}\n</code></pre> <p>If there are multiple levels to the structure of your map, ie. the value of a key in the map is also a map</p> <p>For example, the value of <code>:luke</code> in the <code>star-wars-characters</code> map is represented as a map too <code>{:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}</code></p> <pre><code>(def star-wars-characters\n   {:luke   {:fullname \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"}\n    :vader  {:fullname \"Darth Vader\"    :skill \"Crank phone calls\"}\n    :jarjar {:fullname \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"}})\n</code></pre> <p>To update the skill of one of the characters we can use <code>assoc-in</code> to update the correct value by traversing the map via the given keys.</p> <pre><code>(assoc-in star-wars-characters [:vader :skill] \"The Dark Side of the Force\")\n\n;; =&gt; {:luke {:fullname \"Luke Skywalker\", :skill \"Targeting Swamp Rats\"},\n       :vader {:fullname \"Darth Vader\", :skill \"The Dark Side of the Force\"},\n       :jarjar {:fullname \"JarJar Binks\", :skill \"Upsetting a generation of fans\"}}\n</code></pre>"},{"location":"modifying-data-structures/maps/#update-values-in-a-map-with-update","title":"Update values in a map with <code>update</code>","text":"<p>Rather than replace the current value with one specified, <code>update</code> applies a function to the existing value in order to update that value.</p> <pre><code>(def alphabet-soup {:a 1 :b 2 :c 3})\n\n(update alphabet-soup :a inc)\n\n;; =&gt; {:a 2, :b 2, :c 3}\n</code></pre> <p>Hint As with <code>assoc</code> you can also use <code>update</code> on nested maps using the <code>update-in</code> function.</p>"},{"location":"modifying-data-structures/sets/","title":"Sets","text":""},{"location":"modifying-data-structures/vectors/","title":"Vectors","text":""},{"location":"performance/","title":"Clojure Performance and benchmarks","text":"<p>There are several aspects to performance testing</p> <ul> <li>time taken by individual functions / expressions</li> <li>time through a specific path in your application</li> <li>response times under different loads</li> </ul> <p>The purpose of performance testing and bench-marking is to understand the expected behaviour of your application under various usage patterns.  This kind of testing can also suggest areas of the application that might benefit from optimisation</p>"},{"location":"performance/#performance-tools-for-clojure","title":"Performance tools for Clojure","text":"<ul> <li>Criterium - benchmarks for Clojure expressions</li> <li>Gatling</li> </ul>"},{"location":"performance/#gatling","title":"Gatling","text":"<p>The Gatling Project is a free and open source performance testing tool. Gatling has a basic GUI that's limited to test recorder only. However, the tests can be developed in easily readable/writable domain-specific language (DSL).</p> <p>Key Features of Gatling:</p> <ul> <li>HTTP Recorder</li> <li>An expressive self-explanatory DSL for test development</li> <li>Scala-based</li> <li>Production of higher load using an asynchronous non-blocking approach</li> <li>Full support of HTTP(S) protocols and can also be used for JDBC and JMS load testing</li> <li>Multiple input sources for data-driven tests</li> <li>Powerful and flexible validation and assertions system</li> <li>Comprehensive informative load reports</li> </ul>"},{"location":"performance/#reference-other-performance-tools","title":"Reference: Other performance tools","text":"<p>Other notable performance tools include:</p> <ul> <li>The Grinder</li> <li>Apache JMeter (Java desktop app)</li> <li>Tsung (required Erlang)</li> <li>Locust (python)</li> </ul> <p>Key Features of The Grinder:</p> <ul> <li>TCP proxy to record network activity into the Grinder test script</li> <li>Distributed testing that scales with an the increasing number of agent instances</li> <li>Power of Python or Closure, combined with any Java API, for test script creation or modification</li> <li>Flexible parameterization, which includes creating test data on the fly and the ability to use external data sources like files and databases</li> <li>Post-processing and assertion with full access to test results for correlation and content verification</li> <li>Support of multiple protocols</li> </ul> <p>Key Features of JMeter:</p> <ul> <li>Desktop GUI tool</li> <li>Cross-platform. JMeter can run on any operating system with Java</li> <li>Scalable. When you need a higher load than a single machine can create, JMeter can execute in a distributed mode, meaning one master JMeter machine controls a number of remote hosts.</li> <li>Multi-protocol support. The following protocols are all supported out-of-the-box: HTTP, SMTP, POP3, LDAP, JDBC, FTP, JMS, SOAP, TCP</li> <li>Multiple implementations of pre- and post-processors around sampler. This provides advanced setup, teardo* wn parametrization, and correlation capabilities</li> <li>Various assertions to define criteria</li> <li>Multiple built-in and external listeners to visualize and analyze performance test results</li> <li>Integration with major build and continuous integration systems, making JMeter performance tests part of the full software development life cycle</li> <li>Extensions via plugins</li> </ul>"},{"location":"performance/#resources","title":"Resources","text":"<ul> <li>Open source load testing tools - which one should you use</li> </ul>"},{"location":"performance/load-testing/","title":"Load Testing","text":"<p>The Gatling project can be used to create and run load tests using Clojure (and get fancy reports).</p> <p>Add the following to your project.clj :dependencies</p> <pre><code>[clj-gatling \"0.11.0\"]\n</code></pre>"},{"location":"performance/load-testing/#describe-a-load-test","title":"Describe a Load Test","text":"<p>This is how we would write a simple load test which performs 50 GET requests against a server running at test.com:</p> <pre><code>class SimpleSimulation extends Simulation {\n  //declare a scenario with a simple get request performed 5 times\n  val scn = scenario(\"myScenario\")\n            .exec(http(\"myRequest\").get(\"http://test.com/page.html\"))\n            .repeat(5)\n\n  //run the scenario with 10 concurrent users\n  setUp(scn.users(10))\n}\n</code></pre> <p>Gatling refers to load tests as Simulations which have one or more Scenarios. In the one above we are saying we will have 10 users execute 5 requests each in parallel. We could provide a Content-Type header with the request and check for a 200 response code like this:</p> <pre><code>http(\"myRequest\")\n  .get(\"http://test.com/page.html\")\n  .header(\"Content-Type\", \"text/html\")\n  .check(status.is(200))\nIf we wanted to do a POST request with a JSON body and basic authentication, as well as verify something in the response:\n\nhttp(\"myRequest\")\n  .post(\"http://test.com/someresource\"))\n  .body(StringBody(\"\"\"{ \"myContent\": \"myValue\" }\"\"\"))\n  .asJSON\n  .basicAuth(\"username\", \"password\")\n  .check(jsonPath(\"$..someField\").is(\"some value\"))\n</code></pre> <p>The expression used to extract someField from the response is passed to jsonPath() and is based on Goessner\u2019s JsonPath syntax. We use is() to verify the expected value is equal to some value. We can also do other forms of verification on the response json like:</p> <ul> <li>not(expectedValue): not equal to expectedValue</li> <li>in(sequence): to check that a value belongs to the given sequence</li> <li>exists(), notExists(): to check for the presence/absence of a field</li> </ul> <p>For a multipart request with 2 parts and gzip compression:</p> <pre><code>http(\"myRequest\")\n  .post(\"http://test.com/someresource\"))\n  .bodyPart(StringBodyPart(\"\"\"{ \"myContent\": \"myValue\" }\"\"\"))\n  .bodyPart(RawFileBodyPart(\"file\", \"test.txt\")\n  .processRequestBody(gzipBody)\nWe can also create scenarios with multiple requests and use the result from previous requests in subsequent requests like this:\n\nscenario(\"myScenario\")\n  .exec(http(\"request1\")\n          .post(\"http://test.com/resource1\")\n          .body(StringBody\"\"\"{ \"myContent\": \"\"}\"\"\")\n          .check(jsonPath(\"$..myResponse.guid\").saveAs(\"guid\")))\n  .exec(http(\"request2\")\n          .put(\"http://test.com/resource2/${guid}\")\n          .body(StringBody\"\"\"{ \"someOtherField\": \"\"}\"\"\"))\n</code></pre> <p>guid is extracted from the response of the first call using saveAs(\"guid\") and used in the path to the PUT call.</p> <p>Scenarios can also be run with a ramp up. If we wanted to run the scenario above with 1000 users with a ramp up of 20 seconds we would do:</p> <pre><code>setUp(scn.users(1000).ramp(20))\n</code></pre>"},{"location":"performance/load-testing/#run-a-simulation","title":"Run a Simulation","text":"<p>There are a number of ways to run Gatling simulations. You can download the bundle, place your simulations under the user-files/simulations directory and then run bin/gatling.sh.</p> <p>If you prefer integration with your build system there are plugins for Maven, Gradle and SBT. For example, for Maven we just add the dependencies in the pom.xml:</p> <pre><code>&lt;dependencies&gt;\n  &lt;dependency&gt;\n    &lt;groupId&gt;io.gatling.highcharts&lt;/groupId&gt;\n    &lt;artifactId&gt;gatling-charts-highcharts&lt;/artifactId&gt;\n    &lt;scope&gt;test&lt;/scope&gt;\n  &lt;/dependency&gt;\n&lt;/dependencies&gt;\n\n&lt;build&gt;\n   &lt;plugins&gt;\n     &lt;plugin&gt;\n       &lt;groupId&gt;io.gatling&lt;/groupId&gt;\n       &lt;artifactId&gt;gatling-maven-plugin&lt;/artifactId&gt;\n     &lt;/plugin&gt;\n   &lt;/plugins&gt;\n&lt;/build&gt;\n</code></pre> <p>Place simulations under src/test/scala/com/company/service and then in the terminal:</p> <pre><code>mvn gatling:execute -Dgatling.simulationClass=com.company.service.YourSimulation\n</code></pre>"},{"location":"performance/testing-functions/","title":"Testing Functions","text":""},{"location":"performance/testing-functions/#adding-the-criterium-library","title":"Adding the Criterium library","text":"<p>Add <code>[criterium \"0.4.4\"]</code> to you <code>project.clj</code> file.</p> <p>Add criterium to the namespace were you run your tests</p> <pre><code>(ns ,,,\n  :require [criterium.core] :refer [quick-bench])\n</code></pre> <p>Or simply require criterium in the REPL</p> <pre><code>(require '[criterium.core] :refer [quick-bench])\n</code></pre>"},{"location":"performance/testing-functions/#using-criterium-to-test-code","title":"Using Criterium to test code","text":"<p>Lets try a few similar Clojure functions to see the Criterium benchmark in action</p> <pre><code>(let [number 5]\n  (quick-bench (cond = 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <p>Benchmark output is sent to the REPL</p> <pre><code>Evaluation count : 50788488 in 6 samples of 8464748 calls.\n             Execution time mean : 2.535916 ns\n    Execution time std-deviation : 0.096838 ns\n   Execution time lower quantile : 2.435814 ns ( 2.5%)\n   Execution time upper quantile : 2.686146 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 13.8889 % Variance is moderately inflated by outliers\n</code></pre> <p>Running the benchmark again for the same expression, we get pretty consistent results</p> <pre><code>Evaluation count : 50408712 in 6 samples of 8401452 calls.\n             Execution time mean : 2.571379 ns\n    Execution time std-deviation : 0.163071 ns\n   Execution time lower quantile : 2.366952 ns ( 2.5%)\n   Execution time upper quantile : 2.721099 ns (97.5%)\n                   Overhead used : 9.431514 ns\n</code></pre> <p>There is a parallized version of <code>cond</code> called <code>condp</code>.</p> <pre><code>(let [number 5]\n  (quick-bench (condp = 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <pre><code>Evaluation count : 3625284 in 6 samples of 604214 calls.\n             Execution time mean : 156.813816 ns\n    Execution time std-deviation : 2.560629 ns\n   Execution time lower quantile : 154.222522 ns ( 2.5%)\n   Execution time upper quantile : 160.425030 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 13.8889 % Variance is moderately inflated by outliers\n</code></pre> <p>That figure is quite high, lets run that again.</p> <pre><code>Evaluation count : 3707922 in 6 samples of 617987 calls.\n             Execution time mean : 154.219102 ns\n    Execution time std-deviation : 3.427811 ns\n   Execution time lower quantile : 149.777377 ns ( 2.5%)\n   Execution time upper quantile : 159.225180 ns (97.5%)\n                   Overhead used : 9.431514 ns\n</code></pre> <p>So using a parallized version of a function adds a significant exectution time.  I believe the extra time is due to setting up a thread.  If so, then when using <code>condp</code> you only get a more effective throughput when running multiple parallel threads, which should be fairly obvious.</p> <p>Now lets benchmark a similar function called <code>case</code>.  This function is nicely optimised on the JVM especially when the values are sequential, so we should see faster results</p> <pre><code>(let [number 5]\n  (quick-bench (case 5 1 1 2 2 3 3 4 4 5 5)))\n</code></pre> <p>Benchmark output is sent to the REPL</p> <pre><code>Evaluation count : 56533626 in 6 samples of 9422271 calls.\n             Execution time mean : 1.158650 ns\n    Execution time std-deviation : 0.187322 ns\n   Execution time lower quantile : 1.021431 ns ( 2.5%)\n   Execution time upper quantile : 1.471115 ns (97.5%)\n                   Overhead used : 9.431514 ns\n\nFound 1 outliers in 6 samples (16.6667 %)\n    low-severe   1 (16.6667 %)\n Variance from outliers : 47.5092 % Variance is moderately inflated by outliers\n</code></pre>"},{"location":"puzzles/","title":"Puzzles","text":"<p>Simple puzzles to help you start thinking functionally</p>"},{"location":"puzzles/random-seat-assignment/","title":"Random Seat assignment","text":"<p>https://github.com/practicalli/clojure-practicalli-content/issues/4</p> <p>Take a functional / data oriented approach to solving this problem</p>"},{"location":"puzzles/random-seat-assignment/#description","title":"Description","text":"<p>You want to randomly assign seating to a number of people for a fixed number of seats. Each seat is represented by an integer number between 1 and 30.</p> <p>How do you randomly assign seats without choosing the same seat twice.</p>"},{"location":"puzzles/random-seat-assignment/#loop-recur-approach","title":"Loop / recur approach","text":"<p>Bad...</p>"},{"location":"puzzles/random-seat-assignment/#recursive-function","title":"recursive function","text":""},{"location":"quickstart/quick-reference/","title":"Clojure Quick Reference","text":"<p>The basic Clojure syntax and a few common functions you should probably learn first.</p> <p>Also see the Clojure.org cheat-sheet</p>"},{"location":"quickstart/quick-reference/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is treated as a call to a function. This is known as prefix notation which greatly simplifies Clojure syntax and makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p> <pre><code>(+ 2 3 5 8 13 (* 3 7))\n(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n(clojure-version)\n</code></pre> <p>Functions contain doc-strings and you can ask for a functions documentation, or show the source code.</p> <pre><code>(doc doc)\n(source doc)\n</code></pre> <p>Clojure is a dynamically typed language, it is also strongly typed (everything is a type, but you dont have to express the type in your code).  The type of anything in Clojure can be returned.</p> <pre><code>(type 42)\n(type {:hash \"data\" :map \"more data\"})\n</code></pre>"},{"location":"quickstart/quick-reference/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <pre><code>(str \"lists used mainly\" (* 2 2) :code)\n\n[0 \"indexed array\"]\n\n{:key \"value\" :pairs \"hash-map\" :aka \"dictionary\"}\n\n#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre>"},{"location":"quickstart/quick-reference/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>Names can be bound to any values, simple values like numbers, collections or functions.  A convenient way to refer to value in your code.</p> <pre><code>(def public-health-data\n  ({:date \"2020-01-01\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-03\" :confirmed-cases 23014 :recovery-percent 15}))\n\n(def add-hundred (partial + 100))\n</code></pre>"},{"location":"quickstart/quick-reference/#map-reduce-filter","title":"map reduce filter","text":"<p>Common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n\n(filter even? [1 3 5 8 13 21 34])\n\n(reduce + [31 28 30 31 30 31])\n</code></pre>"},{"location":"quickstart/quick-reference/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p>"},{"location":"quickstart/quick-reference/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(fn [x] (* x x))\n\n(map (fn [x] (* x x)) [1 2 3 4 5])\n</code></pre>"},{"location":"quickstart/quick-reference/#ratio-type","title":"Ratio Type","text":"<p>; Using the division function (/ ) shows another interesting characteristic of Clojure, the fact that it is lazy.  This is not lazy in a bad way, but lazy evaluation of data structures.  This actually helps to make clojure more efficient at dealing with data, especially very large data sets.</p> <pre><code>(/ 22 7)\n22/7\n\n(/ 22 7.0)\n3.142857142857143\n\n(type (/ 22 7))\n</code></pre> <p>Using a Ratio means that the mathematical division is not evaluated when using whole numbers (Integers) that would produce a decimal number.  If you do return a decimal number then what precision of decimal are you expecting.  By specifying one or more of the numbers as a decimal value you are giving Clojure a precision to infer and can therefore provide a specific decimal result.</p>"},{"location":"quickstart/quick-reference/#java-interoperability","title":"Java interoperability","text":"<p><code>.</code> and <code>new</code> are Clojure functions that create a Java object. This allows you to use values from Java constants, i.e. PI is a static double from the java.lang.Math object</p> <pre><code>(. Math PI)\n3.141592653589793\n</code></pre> <p>Also call static and instance methods from Java objects.</p> <pre><code>(Math/cos 3)\n\n(javax.swing.JOptionPane/showMessageDialog nil\n    \"Hello Java Developers\")\n</code></pre>"},{"location":"quickstart/quick-reference/#recursion","title":"Recursion","text":"<p>Recursive function</p> <pre><code>(defn recursive-counter\n  [value]\n  (if (&lt; value 1000)\n    (recur (+ value 25))))\n\n(recursive-counter 100)\n</code></pre>"},{"location":"reference/","title":"Reference","text":""},{"location":"reference/basic-syntax/","title":"Reference: Basic Syntax","text":""},{"location":"reference/basic-syntax/#notes-from-aphyr","title":"Notes from Aphyr","text":"<p>Let\u2019s write a simple program. The simplest, in fact. Type \u201cnil\u201d, and hit enter.</p> <p>user=&gt; nil nil nil is the most basic value in Clojure. It represents emptiness, nothing-doing, not-a-thing. The absence of information.</p> <p>user=&gt; true true user=&gt; false false true and false are a pair of special values called Booleans. They mean exactly what you think: whether a statement is true or false. true, false, and nil form the three poles of the Lisp logical system.</p> <p>user=&gt; 0 0 This is the number zero. Its numeric friends are 1, -47, 1.2e-4, 1/3, and so on. We might also talk about strings, which are chunks of text surrounded by double quotes:</p> <p>user=&gt; \"hi there!\" \"hi there!\" nil, true, 0, and \"hi there!\" are all different types of values; the nouns of programming. Just as one could say \u201cHouse.\u201d in English, we can write a program like \"hello, world\" and it evaluates to itself: the string \"hello world\". But most sentences aren\u2019t just about stating the existence of a thing; they involve action. We need verbs.</p> <p>user=&gt; inc</p>"},{"location":"reference/basic-syntax/#_1","title":"<p>This is a verb called inc\u2013short for \u201cincrement\u201d. Specifically, inc is a symbol which points to a verb: #\u2013 just like the word \u201crun\u201d is a name for the concept of running. <p>There\u2019s a key distinction here\u2013that a signifier, a reference, a label, is not the same as the signified, the referent, the concept itself. If you write the word \u201crun\u201d on paper, the ink means nothing by itself. It\u2019s just a symbol. But in the mind of a reader, that symbol takes on meaning; the idea of running.</p> <p>Unlike the number 0, or the string \u201chi\u201d, symbols are references to other values. when Clojure evaluates a symbol, it looks up that symbol\u2019s meaning. Look up inc, and you get #. <p>Can we refer to the symbol itself, without looking up its meaning?</p> <p>user=&gt; 'inc inc Yes. The single quote ' escapes a sentence. In programming languages, we call sentences expressions or statements. A quote says \u201cRather than evaluating this expression\u2019s text, simply return the text itself, unchanged.\u201d Quote a symbol, get a symbol. Quote a number, get a number. Quote anything, and get it back exactly as it came in.</p> <p>user=&gt; '123 123 user=&gt; '\"foo\" \"foo\" user=&gt; '(1 2 3) (1 2 3) A new kind of value, surrounded by parentheses: the list. LISP originally stood for LISt Processing, and lists are still at the core of the language. In fact, they form the most basic way to compose expressions, or sentences. A list is a single expression which has multiple parts. For instance, this list contains three elements: the numbers 1, 2, and 3. Lists can contain anything: numbers, strings, even other lists:</p> <p>user=&gt; '(nil \"hi\") (nil \"hi\") A list containing two elements: the number 1, and a second list. That list contains two elements: the number 2, and another list. That list contains two elements: 3, and an empty list.</p> <p>user=&gt; '(1 (2 (3 ()))) (1 (2 (3 ()))) You could think of this structure as a tree\u2013which is a provocative idea, because languages are like trees too: sentences are comprised of clauses, which can be nested, and each clause may have subjects modified by adjectives, and verbs modified by adverbs, and so on. \u201cLindsay, my best friend, took the dog which we found together at the pound on fourth street, for a walk with her mother Michelle.\u201d</p> <p>Took   Lindsay     my best friend   the dog     which we found together       at the pound         on fourth street     for a walk       with her mother         Michelle But let\u2019s try something simpler. Something we know how to talk about. \u201cIncrement the number zero.\u201d As a tree:</p> <p>Increment   the number zero We have a symbol for incrementing, and we know how to write the number zero. Let\u2019s combine them in a list:</p> <p>clj=&gt; '(inc 0) (inc 0) A basic sentence. Remember, since it\u2019s quoted, we\u2019re talking about the tree, the text, the expression, by itself. Absent interpretation. If we remove the single-quote, Clojure will interpret the expression:</p> <p>user=&gt; (inc 0) 1 Incrementing zero yields one. And if we wanted to increment that value?</p> <p>Increment   increment     the number zero user=&gt; (inc (inc 0)) 2 A sentence in Lisp is a list. It starts with a verb, and is followed by zero or more objects for that verb to act on. Each part of the list can itself be another list, in which case that nested list is evaluated first, just like a nested clause in a sentence. When we type</p> <p>(inc (inc 0)) Clojure first looks up the meanings for the symbols in the code:</p> <p>(#   (#     0)) Then evaluates the innermost list (inc 0), which becomes the number 1: <p>(#  1) Finally, it evaluates the outer list, incrementing the number 1: <p>2 Every list starts with a verb. Parts of a list are evaluated from left to right. Innermost lists are evaluated before outer lists.</p> <p>(+ 1 (- 5 2) (+ 3 4)) (+ 1 3       (+ 3 4)) (+ 1 3       7) 11 That\u2019s it.</p> <p>The entire grammar of Lisp: the structure for every expression in the language. We transform expressions by substituting meanings for symbols, and obtain some result. This is the core of the Lambda Calculus, and it is the theoretical basis for almost all computer languages. Ruby, Javascript, C, Haskell; all languages express the text of their programs in different ways, but internally all construct a tree of expressions. Lisp simply makes it explicit.</p>","text":""},{"location":"reference/books/","title":"Books &amp; Tutorials on Clojure","text":"<p>Here is a list of Clojure books, grouped by skill level.  There is also a book list on Clojure.org or via a search for Clojure on o'Reilly lists most of these books.</p>"},{"location":"reference/books/#for-clojure-beginners","title":"For Clojure beginners","text":"<ul> <li>Living Clojure, O'Reilly April 2015</li> <li>Clojure for the Brave and the True, NoStartch Press September 2015</li> <li>Clojurescript Unraveled - June 2016</li> <li>Clojure from the ground up</li> <li>Practicalli Clojure</li> <li>Practicalli Clojure WebApps</li> </ul>"},{"location":"reference/books/#reference","title":"Reference","text":"<ul> <li>Clojure Programming Cookbook, Packt August 2016</li> <li>Clojure Cookbook, O'Reilly March 2014 - hundreds of real-world problems and solutions, ranging from basic utilities to rich web services to heavy data processing</li> </ul>"},{"location":"reference/books/#intermediate-level","title":"Intermediate level","text":"<ul> <li>Web Development with Clojure, Pragmatic July 2016</li> <li>Mastering Clojure, Packt March 2016</li> <li>Clojure in Action, Manning December 2015</li> <li>Programming Clojure, Pragmatic October 2015</li> <li>Clojure Applied: From Practice to Practitioner, Pragmatic September 2015</li> <li>Joy of Clojure, Manning May 2014</li> <li>Clojure Programming, O'Reilly March 2012</li> </ul>"},{"location":"reference/books/#other-books","title":"Other books","text":"<ul> <li>Learning Clojurescript, Packt June 2016</li> <li>Professional Clojure, Wiley/Wrox May 2016</li> <li>Clojure for Java Developers, Packt February 2016</li> <li>Clojure for Finance, January 2016</li> <li>Clojure Recipes, Addison-Wesley October 2015</li> <li>Clojure for Data Science, Packt September 2015</li> <li>Clojure High Performance Programming, Packt September 2015</li> <li>Clojure Data Structures &amp; Algorithms, Packt August 2015</li> <li>Mastering Clojure Data Analysis, Packt</li> <li>Clojure Reactive Programming, Packt March 2015</li> <li>Clojure Web Development Essentials, Packt February 2015</li> <li>Clojure Data Analysis Cookbook, Packt January 2015</li> <li>Mastering Clojure Macros, Pragmatic August 2014</li> <li>Clojure for Machine Learning, Packt April 2014</li> <li>Clojure for Domain-specific Languages, Packt December 2013</li> <li>Clojurescript: Up and Running, O'Reilly October 2012</li> <li>Building Web Applications with Clojure, Packt April 2012</li> <li>Functional Programming Patterns in Scala and Clojure, Pragmatic August 2014</li> </ul>"},{"location":"reference/changing-state/","title":"Changing State","text":""},{"location":"reference/code-analysis/","title":"Code Analysis","text":"<p>clj-kondo is a lint tool that highlights syntactic errors and suggests idioms for Clojure, ClojureScript and EDN.</p> <p>Use clj-kondo with your preferred editor to warning about errors as you type so issues can be fixed as soon as they occur, enhancing your joy of Clojure.</p> <p>clj-kondo can also be used as a command line tool for checking projects in development environments and continuous integration service, such as the setup-clojure GitHub action.</p> <p>Clojure LSP includes clj-kondo</p> <p>Clojure LSP install includes clj-kondo, removing the need for a separate install of clj-kondo</p>"},{"location":"reference/code-analysis/#install","title":"Install","text":"<p>Follow the clj-kondo install guide for your operating system.</p> <p>Clj-kondo config contains additional configuration for using clj-kondo with libraries that extend the Clojure language via macros.</p> SpacemacsDoom EmacsNeovim <p></p> <p>clj-kondo can be used if <code>cider</code> is configured as the clojure layer backend. If LSP is configured as the backend, should not be used as it may duplicate analysis results (e.g. doubling error and warning messgeas).</p> <p>Use Clojure LSP with Doom rather than clj-kondo by itself.</p> <p>Add the  <code>+lsp</code> feature to the Clojure module and enable the <code>lsp</code> module .config/doom/init.el<pre><code>(clojure +lsp)\nlsp\n</code></pre> Add the respective LSP server implementation to the operating system</p> <p>Practicalli Neovim provides a guide to configure Neovim with Treesitter as an LSP client, as well as a fennel based configuration for Neovim.</p>"},{"location":"reference/code-analysis/#command-line-analysis","title":"Command Line analysis","text":"<p>Run <code>clj-kondo</code> with the --lint option and specify a file or path</p> <p>To analyse a specific file</p> <pre><code>clj-kondon --lint ~/.config/deps.edn\n</code></pre> <p>Analyse a project, running the clj-kondo command from the root of the project</p> <pre><code>clj-kondon --lint .\n</code></pre>"},{"location":"reference/code-analysis/#clj-kondo-with-github-actions","title":"clj-kondo with GitHub actions","text":"<p>Add clj-kondo linting to continuous integration workflow.</p> <p></p>"},{"location":"reference/control-flow/","title":"Control Flow","text":""},{"location":"reference/core-async/","title":"Core.async","text":""},{"location":"reference/doc-and-source-functions/","title":"Doc and source functions","text":""},{"location":"reference/doc-and-source-functions/#the-doc-source-functions","title":"The doc &amp; source functions","text":"<p>If you are not using a Clojure aware editor or spend a lot of time in the REPL you can also view the documentation of a function by calling the <code>doc</code> function and see the source by calling the <code>source</code> function.</p> <p>To use the <code>doc</code> &amp; <code>source</code> functions in the REPL you should be in the <code>user</code> namespace.</p> <p>Note On the command line, start a REPL with the command <code>lein repl</code> and then view the documentation for three common functions used in clojure</p> <p>Make sure you are in the <code>user</code> namespace before calling the <code>doc</code> function.  If you are in another namespace, either change back using <code>(ns 'user)</code> or see the next section on using these functions in another namespace.</p> <pre><code>(doc doc)\n(doc map)\n(doc filter)\n(doc cons)\n\n(source doc)\n(source map)\n</code></pre> <p>Here is the doc string for <code>doc</code></p> <p></p> <p>Here is the source code for the <code>source</code> function</p> <p></p> <p>Hint As the documentation for a function is part of its definition, by looking at the source of a function you also get the documentation.</p>"},{"location":"reference/doc-and-source-functions/#using-doc-source-function-from-another-namespace","title":"Using doc &amp; source function from another namespace","text":"<p>The <code>doc</code> and <code>source</code> functions are only included in the <code>user</code> namespace. If you switch to another namespace or your editor places you in the current namespace of your project, these functions will not be available unless you including <code>core.repl</code> in the current namespace.</p> <p>From the REPL, evaluate the expression:</p> <pre><code>(use 'clojure.repl)\n</code></pre> <p>You could also <code>require</code> the <code>clojure.repl</code> library in your own code, however if you have a good editor it should provide these features without including this library.  Therefore the following code is shown only as an example and not a recommended approach.</p> <pre><code>(ns foobar\n(:require [clojure.repl :refer :all]))\n</code></pre>"},{"location":"reference/kebab-case/","title":"Clojure names use kebab-case","text":"<p>kebab-case is a clean, human-readable way to combine the words that would otherwise have spaces.</p> <p>Cloure uses kebab-case to combines words with a dash, <code>-</code>, rather than a space. e.g. <code>rock-paper-scissors</code>,  <code>tic-tac-toe</code> or <code>(def db-spec-development {:db-type \"h2\" :db-name \"banking-on-clojure\"})</code></p> <p>kebab-case is used throughout Clojure, including</p> <ul> <li>Var names with <code>def</code> and function names with <code>defn</code></li> <li>Local names with <code>let</code></li> <li>Clojure spec names</li> </ul> <p>kebab-case is used in lisp languages including Clojure. The style is also used in website URLs, e.g. practicalli.github.io/clojure-webapps</p>"},{"location":"reference/kebab-case/#using-meaningful-names","title":"Using meaningful names","text":"<p>To provide greater clarity to human developers, words may be combined for the names used when writing the code. Using multiple words can give greater context in to the purpose of that code.</p> <p>Using a combination of meaningful names makes understanding and debugging code far easier.</p>"},{"location":"reference/kebab-case/#spaces-characters-have-special-meaning","title":"Spaces characters have special meaning","text":"<p>Programming languages remove spaces between words because the space character is used as a separator when parsing the code.</p> <p>If spaces were not used as a separator for the some other character would be required, adding complexity to the language syntax.</p>"},{"location":"reference/kebab-case/#other-styles","title":"Other Styles","text":"<ul> <li>camelCase - used in Java and C-style programming languages</li> <li>PascalCase - used in the Pascal programming language</li> <li>snake_case - used for <code>ENVIRONMENT_VARIABLES</code> and <code>database_table_names_and_columns</code></li> </ul>"},{"location":"reference/naming-conventions/","title":"Naming Conventions","text":""},{"location":"reference/naming-conventions/#kebab-case","title":"Kebab-case","text":"<p>Kebab-case is the naming convention for all Clojure function names than contain more than one word.  Its name comes from the Shish Kebab style of cooking, where the words are the tofu and vegetables and the dashes are the skewers.</p> <pre><code>clj-time\nstring-parser\ndisplay-name\n</code></pre>"},{"location":"reference/naming-conventions/#predicates","title":"Predicates","text":"<p>Examples of predicate naming conventions from <code>clojure.core</code></p> <pre><code>contains?\nempty?\nevery?\nnot-empty?\nnull?\n</code></pre>"},{"location":"reference/naming-conventions/#namespace-requires-and-aliases","title":"Namespace requires and aliases","text":"<p>Required libraries should be given a contextually meaningful name as an alias, helping to identify the purpose of functions defined outside of the namespace.</p> <p>Giving meaningful context helps code to be understood by any person reading the code.  It is also easier to search for usage of functions from that context in the current project.</p> <p>Aliases are rarely typed more than once in full as Clojure editors have auto-complete, so there is no benefit to short of single character aliases.</p> <pre><code>(ns status-monitor.handler\n  (:require [hiccup.page :refer :as web-page]\n            [hiccup.form :refer :as web-form]))\n</code></pre> <p>In very commonly used libraries or very highly used functions through out the code, refer those functions explicitly</p> <pre><code>(ns naming.is.hard\n  (:require [compojure.core :refer [defroutes GET POST]]\n            [ring.middleware.defaults :refer [wrap-defaults site-defaults]]))\n</code></pre>"},{"location":"reference/naming-conventions/#converting-functions","title":"Converting functions","text":"<p>When a function takes values in one format or type and converts them to another</p> <p>Examples</p> <pre><code>md-&gt;html\n\nmap-&gt;Record-name  ; map factory function of a record -- creates a new record from a map\n-&gt;Record-name     ; positional factory function of a record -- creates a new record from a list of values\n</code></pre>"},{"location":"reference/naming/","title":"Naming","text":""},{"location":"reference/prasmatic-schema/","title":"Prasmatic Schema","text":""},{"location":"reference/reader-macros/","title":"Reader Macros","text":"<p>This is a collection of reader macros (think syntactic sugar) that are valid in Clojure.  These macros are useful for commenting out expressions, defining sets, ...</p> <p>Many reader macros start with the character #, which is in fact the Dispatch macro that tells the Clojure reader (the thing that takes a file of Clojure text and parses it for consumption in the compiler) to go and look at another read table for the definition of the next character - in essence this allows extending default reader behaviour.</p> <ul> <li> <p>#_ - Discard macro - ignore the next expression.  Often used to comment out code, especially when nested inside other expressions</p> </li> <li> <p>#' - Var macro - returns the reference to the var.  Used to pass the definition of something rather than the result of evaluating it.</p> </li> </ul> <p>There is a nice list of reader macros in the article: The weird and wonderful characters of Clojure by @kouphax.</p> <p>Hint Reader macros are part of the Clojure language specification, so are different to macros, which can be defined by anyone.</p>"},{"location":"reference/reader-macros/#todore-write","title":"Todo::Re-write","text":""},{"location":"reference/recursion/","title":"Recursion","text":"<p>Recursion is a highly valuable tool in functional programming as it provides an idiomatic way of processing collections of data.</p>"},{"location":"reference/recursion/#normal-recursion-is-more-idiomatic","title":"normal recursion is more idiomatic","text":"<p>On average it tends to give you clearer, more functional code whereas loop/recur tens to push you more towards an imperative, iterative style.</p>"},{"location":"reference/recursion/#recursive-functions","title":"Recursive functions","text":""},{"location":"reference/recursion/#warningrecursion-can-hit-the-limit-of-your-heapstack-and-cause-a-exception","title":"Warning::Recursion can hit the limit of your heap/stack and cause a ... exception","text":""},{"location":"reference/recursion/#tail-call-optimisation-with-recur","title":"Tail-call Optimisation with <code>recur</code>","text":"<p>Tail-call optimisation is where a part of memory is over-written by additional calls during recursive calls.  By using the same memory segment each time, then the memory footprint of your code does not increase.</p> <p>Therefore <code>recur</code> is good choice for deeply nested recursion or when manipulating larger (non-lazy) data structures.</p> <p>Without tail-call optimisation the code may otherwise cause a StackOverflow / Heap out of memory Error</p>"},{"location":"reference/recursion/#info","title":"Info::","text":"<p>Using the <code>recur</code> function as the last line of a <code>loop</code> or function will enable tail call optimisation.</p>"},{"location":"reference/recursion/#fast","title":"Fast","text":"<p>Using <code>loop</code> and <code>recur</code> it's one of the most efficient constructs in Clojure, match the speed of an equivalent for loop in Java code.</p>"},{"location":"reference/recursion/#restrictions","title":"Restrictions","text":"<p>you can only recur in tail position, you can't do mutual recursion between two different function etc.</p> <p>Sometime it simply isn't possible to use loop/recur or it may require the contort of code to something very unmanageable to do so.</p>"},{"location":"reference/recursion/#hintuse-recur-once-you-have-created-a-new-recursive-function","title":"Hint::Use recur once you have created a new recursive function","text":"<p>By calling a recursive function by name rather than using <code>recur</code> can prevent your code from remaining in an infinite loop if you get a terminating condition wrong.  Without recur you memory space will be eaten up and your code will stop. Once your function is working correctly, then you can replace the call to itself with <code>recur</code>.</p>"},{"location":"reference/recursion/#examples","title":"Examples","text":"<p>Here are two examples using two different recursion approaches. What are the guidelines of usage of one over another?</p> <p>This example recursively calls itself</p> <pre><code>(defn take-while\n  \"Returns a lazy sequence of successive items from coll while\n  (pred item) returns true. pred must be free of side-effects.\"\n  {:added \"1.0\"\n   :static true}\n  [pred coll]\n  (lazy-seq\n   (when-let [s (seq coll)]\n       (when (pred (first s))\n         (cons (first s) (take-while pred (rest s)))))))\n</code></pre> <p>This example uses <code>loop</code> and <code>recur</code> for recursively processing the collection.</p> <pre><code>(defn take-last\n  \"Returns a seq of the last n items in coll.  Depending on the type\n  of coll may be no better than linear time.  For vectors, see also subvec.\"\n  {:added \"1.1\"\n   :static true}\n  [n coll]\n  (loop [s (seq coll), lead (seq (drop n coll))]\n    (if lead\n      (recur (next s) (next lead))\n      s)))\n</code></pre>"},{"location":"reference/recursion/#hint","title":"Hint::","text":"<p>The above example could not use <code>recur</code> instead of the recursive call to <code>take-while</code> as that call is not in the last position. The <code>cons</code> function is in the last position of this function.</p>"},{"location":"reference/recursion/#misc","title":"Misc","text":"<p>The only one reason to use lazy-seq/lazy-cons mechanism is generating lazy sequences. If you don't need them then loop/recur should undoubtedly be used.</p>"},{"location":"reference/sequences/","title":"Reference: Clojure from the ground up: sequences","text":"<p>In Chapter 3, we discovered functions as a way to abstract expressions; to rephrase a particular computation with some parts missing. We used functions to transform a single value. But what if we want to apply a function to more than one value at once? What about sequences?</p> <p>For example, we know that (inc 2) increments the number 2. What if we wanted to increment every number in the vector [1 2 3], producing [2 3 4]?</p> <p>user=&gt; (inc [1 2 3]) ClassCastException clojure.lang.PersistentVector cannot be cast to java.lang.Number  clojure.lang.Numbers.inc (Numbers.java:110) Clearly inc can only work on numbers, not on vectors. We need a different kind of tool.</p> <p>A direct approach Let\u2019s think about the problem in concrete terms. We want to increment each of three elements: the first, second, and third. We know how to get an element from a sequence by using nth, so let\u2019s start with the first number, at index 0:</p> <p>user=&gt; (def numbers [1 2 3])</p>"},{"location":"reference/sequences/#usernumbers","title":"'user/numbers","text":"<p>user=&gt; (nth numbers 0) 1 user=&gt; (inc (nth numbers 0)) 2 So there\u2019s the first element incremented. Now we can do the second:</p> <p>user=&gt; (inc (nth numbers 1)) 3 user=&gt; (inc (nth numbers 2)) 4 And it should be straightforward to combine these into a vector\u2026</p> <p>user=&gt; [(inc (nth numbers 0)) (inc (nth numbers 1)) (inc (nth numbers 2))] [2 3 4] Success! We\u2019ve incremented each of the numbers in the list! How about a list with only two elements?</p> <p>user=&gt; (def numbers [1 2])</p>"},{"location":"reference/sequences/#usernumbers_1","title":"'user/numbers","text":"<p>user=&gt; [(inc (nth numbers 0)) (inc (nth numbers 1)) (inc (nth numbers 2))]</p> <p>IndexOutOfBoundsException   clojure.lang.PersistentVector.arrayFor (PersistentVector.java:107) Shoot. We tried to get the element at index 2, but couldn\u2019t, because numbers only has indices 0 and 1. Clojure calls that \u201cindex out of bounds\u201d.</p> <p>We could just leave off the third expression in the vector; taking only elements 0 and 1. But the problem actually gets much worse, because we\u2019d need to make this change every time we wanted to use a different sized vector. And what of a vector with 1000 elements? We\u2019d need 1000 (inc (nth numbers ...)) expressions! Down this path lies madness.</p> <p>Let\u2019s back up a bit, and try a slightly smaller problem.</p> <p>Recursion What if we just incremented the first number in the vector? How would that work? We know that first finds the first element in a sequence, and rest finds all the remaining ones.</p> <p>user=&gt; (first [1 2 3]) 1 user=&gt; (rest [1 2 3]) (2 3) So there\u2019s the pieces we\u2019d need. To glue them back together, we can use a function called cons, which says \u201cmake a list beginning with the first argument, followed by all the elements in the second argument\u201d.</p> <p>user=&gt; (cons 1 [2]) (1 2) user=&gt; (cons 1 [2 3]) (1 2 3) user=&gt; (cons 1 [2 3 4]) (1 2 3 4) OK so we can split up a sequence, increment the first part, and join them back together. Not so hard, right?</p> <p>(defn inc-first [numbers]   (cons (inc (first numbers))         (rest numbers))) user=&gt; (inc-first [1 2 3 4]) (2 2 3 4) Hey, there we go! First element changed. Will it work with any length list?</p> <p>user=&gt; (inc-first [5]) (6) user=&gt; (inc-first [])</p> <p>NullPointerException   clojure.lang.Numbers.ops (Numbers.java:942) Shoot. We can\u2019t increment the first element of this empty vector, because it doesn\u2019t have a first element.</p> <p>user=&gt; (first []) nil user=&gt; (inc nil)</p> <p>NullPointerException   clojure.lang.Numbers.ops (Numbers.java:942) So there are really two cases for this function. If there is a first element in numbers, we\u2019ll increment it as normal. If there\u2019s no such element, we\u2019ll return an empty list. To express this kind of conditional behavior, we\u2019ll use a Clojure special form called if:</p>"},{"location":"reference/sequences/#user-doc-if","title":"user=&gt; (doc if)","text":"<p>if   (if test then else?) Special Form   Evaluates test. If not the singular values nil or false,   evaluates and yields then, otherwise, evaluates and yields else. If   else is not supplied it defaults to nil.</p> <p>Please see http://clojure.org/special_forms#if To confirm our intuition:</p> <p>user=&gt; (if true :a :b) :a user=&gt; (if false :a :b) :b Seems straightforward enough.</p> <p>(defn inc-first [numbers]   (if (first numbers)     ; If there's a first number, build a new list with cons     (cons (inc (first numbers))           (rest numbers))     ; If there's no first number, just return an empty list     (list)))</p> <p>user=&gt; (inc-first []) () user=&gt; (inc-first [1 2 3]) (2 2 3) Success! Now we can handle both cases: empty sequences, and sequences with things in them. Now how about incrementing that second number? Let\u2019s stare at that code for a bit.</p> <p>(rest numbers) Hang on. That list\u2013(rest numbers)\u2013that\u2019s a list of numbers too. What if we\u2026 used our inc-first function on that list, to increment its first number? Then we\u2019d have incremented both the first and the second element.</p> <p>(defn inc-more [numbers]   (if (first numbers)     (cons (inc (first numbers))           (inc-more (rest numbers)))     (list))) user=&gt; (inc-more [1 2 3 4]) (2 3 4 5) Odd. That didn\u2019t just increment the first two numbers. It incremented all the numbers. We fell into the complete solution entirely by accident. What happened here?</p> <p>Well first we\u2026 yes, we got the number one, and incremented it. Then we stuck that onto (inc-first [2 3 4]), which got two, and incremented it. Then we stuck that two onto (inc-first [3 4]), which got three, and then we did the same for four. Only that time around, at the very end of the list, (rest [4]) would have been empty. So when we went to get the first number of the empty list, we took the second branch of the if, and returned the empty list.</p> <p>Having reached the bottom of the function calls, so to speak, we zip back up the chain. We can imagine this function turning into a long string of cons calls, like so:</p> <p>(cons 2 (cons 3 (cons 4 (cons 5 '())))) (cons 2 (cons 3 (cons 4 '(5)))) (cons 2 (cons 3 '(4 5))) (cons 2 '(3 4 5)) '(2 3 4 5) This technique is called recursion, and it is a fundamental principle in working with collections, sequences, trees, or graphs\u2026 any problem which has small parts linked together. There are two key elements in a recursive program:</p> <p>Some part of the problem which has a known solution A relationship which connects one part of the problem to the next Incrementing the elements of an empty list returns the empty list. This is our base case: the ground to build on. Our inductive case, also called the recurrence relation, is how we broke the problem up into incrementing the first number in the sequence, and incrementing all the numbers in the rest of the sequence. The if expression bound these two cases together into a single function; a function defined in terms of itself.</p> <p>Once the initial step has been taken, every step can be taken.</p> <p>user=&gt; (inc-more [1 2 3 4 5 6 7 8 9 10 11 12]) (2 3 4 5 6 7 8 9 10 11 12 13) This is the beauty of a recursive function; folding an unbounded stream of computation over and over, onto itself, until only a single step remains.</p> <p>Generalizing from inc We set out to increment every number in a vector, but nothing in our solution actually depended on inc. It just as well could have been dec, or str, or keyword. Let\u2019s parameterize our inc-more function to use any transformation of its elements:</p> <p>(defn transform-all [f xs]   (if (first xs)     (cons (f (first xs))           (transform-all f (rest xs)))     (list))) Because we could be talking about any kind of sequence, not just numbers, we\u2019ve named the sequence xs, and its first element x. We also take a function f as an argument, and that function will be applied to each x in turn. So not only can we increment numbers\u2026</p> <p>user=&gt; (transform-all inc [1 2 3 4]) (2 3 4 5) \u2026but we can turn strings to keywords\u2026</p> <p>user=&gt; (transform-all keyword [\"bell\" \"hooks\"]) (:bell :hooks) \u2026or wrap every element in a list:</p> <p>user=&gt; (transform-all list [:codex :book :manuscript]) ((:codex) (:book) (:manuscript)) In short, this function expresses a sequence in which each element is some function applied to the corresponding element in the underlying sequence. This idea is so important that it has its own name, in mathematics, Clojure, and other languages. We call it map.</p> <p>user=&gt; (map inc [1 2 3 4]) (2 3 4 5) You might remember maps as a datatype in Clojure, too\u2013they\u2019re dictionaries that relate keys to values.</p> <p>{:year  1969  :event \"moon landing\"} The function map relates one sequence to another. The type map relates keys to values. There is a deep symmetry between the two: maps are usually sparse, and the relationships between keys and values may be arbitrarily complex. The map function, on the other hand, usually expresses the same type of relationship, applied to a series of elements in fixed order.</p> <p>Building sequences Recursion can do more than just map. We can use it to expand a single value into a sequence of values, each related by some function. For instance:</p> <p>(defn expand [f x count]   (if (pos? count)     (cons x (expand f (f x) (dec count))))) Our base case is x itself, followed by the sequence beginning with (f x). That sequence in turn expands to (f (f x)), and then (f (f (f x))), and so on. Each time we call expand, we count down by one using dec. Once the count is zero, the if returns nil, and evaluation stops. If we start with the number 0 and use inc as our function:</p> <p>user=&gt; user=&gt; (expand inc 0 10) (0 1 2 3 4 5 6 7 8 9) Clojure has a more general form of this function, called iterate.</p> <p>user=&gt; (take 10 (iterate inc 0)) (0 1 2 3 4 5 6 7 8 9) Since this sequence is infinitely long, we\u2019re using take to select only the first 10 elements. We can construct more complex sequences by using more complex functions:</p> <p>user=&gt; (take 10 (iterate (fn [x] (if (odd? x) (+ 1 x) (/ x 2))) 10)) (10 5 6 3 4 2 1 2 1 2) Or build up strings:</p> <p>user=&gt; (take 5 (iterate (fn [x] (str x \"o\")) \"y\")) (\"y\" \"yo\" \"yoo\" \"yooo\" \"yoooo\") iterate is extremely handy for working with infinite sequences, and has some partners in crime. repeat, for instance, constructs a sequence where every element is the same.</p> <p>user=&gt; (take 10 (repeat :hi)) (:hi :hi :hi :hi :hi :hi :hi :hi :hi :hi) user=&gt; (repeat 3 :echo) (:echo :echo :echo) And its close relative repeatedly simply calls a function (f) to generate an infinite sequence of values, over and over again, without any relationship between elements. For an infinite sequence of random numbers:</p> <p>user=&gt; (rand) 0.9002678382322784 user=&gt; (rand) 0.12375594203332863 user=&gt; (take 3 (repeatedly rand)) (0.44442397843046755 0.33668691162169784 0.18244875487846746) Notice that calling (rand) returns a different number each time. We say that rand is an impure function, because it cannot simply be replaced by the same value every time. It does something different each time it\u2019s called.</p> <p>There\u2019s another very handy sequence function specifically for numbers: range, which generates a sequence of numbers between two points. (range n) gives n successive integers starting at 0. (range n m) returns integers from n to m-1. (range n m step) returns integers from n to m, but separated by step.</p> <p>user=&gt; (range 5) (0 1 2 3 4) user=&gt; (range 2 10) (2 3 4 5 6 7 8 9) user=&gt; (range 0 100 5) (0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95) To extend a sequence by repeating it forever, use cycle:</p> <p>user=&gt; (take 10 (cycle [1 2 3])) (1 2 3 1 2 3 1 2 3 1) Transforming sequences Given a sequence, we often want to find a related sequence. map, for instance, applies a function to each element\u2013but has a few more tricks up its sleeve.</p> <p>user=&gt; (map (fn [n vehicle] (str \"I've got \" n \" \" vehicle \"s\"))          [0 200 9]          [\"car\" \"train\" \"kiteboard\"]) (\"I've got 0 cars\" \"I've got 200 trains\" \"I've got 9 kiteboards\") If given multiple sequences, map calls its function with one element from each sequence in turn. So the first value will be (f 0 \"car\"), the second (f 200 \"train\"), and so on. Like a zipper, map folds together corresponding elements from multiple collections. To sum three vectors, column-wise:</p> <p>user=&gt; (map + [1 2 3]               [4 5 6]               [7 8 9]) (12 15 18) If one sequence is bigger than another, map stops at the end of the smaller one. We can exploit this to combine finite and infinite sequences. For example, to number the elements in a vector:</p> <p>user=&gt; (map (fn [index element] (str index \". \" element))             (iterate inc 0)             [\"erlang\" \"ruby\" \"haskell\"]) (\"0. erlang\" \"1. ruby\" \"2. haskell\") Transforming elements together with their indices is so common that Clojure has a special function for it: map-indexed:</p> <p>user=&gt; (map-indexed (fn [index element] (str index \". \" element))                     [\"erlang\" \"ruby\" \"haskell\"]) (\"0. erlang\" \"1. ruby\" \"2. haskell\") You can also tack one sequence onto the end of another, like so:</p> <p>user=&gt; (concat [1 2 3] [:a :b :c] [4 5 6]) (1 2 3 :a :b :c 4 5 6) Another way to combine two sequences is to riffle them together, using interleave.</p> <p>user=&gt; (interleave [:a :b :c] [1 2 3]) (:a 1 :b 2 :c 3) And if you want to insert a specific element between each successive pair in a sequence, try interpose:</p> <p>user=&gt; (interpose :and [1 2 3 4]) (1 :and 2 :and 3 :and 4) To reverse a sequence, use reverse.</p> <p>user=&gt; (reverse [1 2 3]) (3 2 1) user=&gt; (reverse \"woolf\") (\\f \\l \\o \\o \\w) Strings are sequences too! Each element of a string is a character, written \\f. You can rejoin those characters into a string with apply str:</p> <p>user=&gt; (apply str (reverse \"woolf\")) \"floow\" \u2026and break strings up into sequences of chars with seq.</p> <p>user=&gt; (seq \"sato\") (\\s \\a \\t \\o) To randomize the order of a sequence, use shuffle.</p> <p>user=&gt; (shuffle [1 2 3 4]) [3 1 2 4] user=&gt; (apply str (shuffle (seq \"abracadabra\"))) \"acaadabrrab\" Subsequences We\u2019ve already seen take, which selects the first n elements. There\u2019s also drop, which removes the first n elements.</p> <p>user=&gt; (range 10) (0 1 2 3 4 5 6 7 8 9) user=&gt; (take 3 (range 10)) (0 1 2) user=&gt; (drop 3 (range 10)) (3 4 5 6 7 8 9) And for slicing apart the other end of the sequence, we have take-last and drop-last:</p> <p>user=&gt; (take-last 3 (range 10)) (7 8 9) user=&gt; (drop-last 3 (range 10)) (0 1 2 3 4 5 6) take-while and drop-while work just like take and drop, but use a function to decide when to cut.</p> <p>user=&gt; (take-while pos? [3 2 1 0 -1 -2 10]) (3 2 1) In general, one can cut a sequence in twain by using split-at, and giving it a particular index. There\u2019s also split-with, which uses a function to decide when to cut.</p> <p>(split-at 4 (range 10)) [(0 1 2 3) (4 5 6 7 8 9)] user=&gt; (split-with number? [1 2 3 :mark 4 5 6 :mark 7]) [(1 2 3) (:mark 4 5 6 :mark 7)] Notice that because indexes start at zero, sequence functions tend to have predictable numbers of elements. (split-at 4) yields four elements in the first collection, and ensures the second collection begins at index four. (range 10) has ten elements, corresponding to the first ten indices in a sequence. (range 3 5) has two (since 5 - 3 is two) elements. These choices simplify the definition of recursive functions as well.</p> <p>We can select particular elements from a sequence by applying a function. To find all positive numbers in a list, use filter:</p> <p>user=&gt; (filter pos? [1 5 -4 -7 3 0]) (1 5 3) filter looks at each element in turn, and includes it in the resulting sequence only if (f element) returns a truthy value. Its complement is remove, which only includes those elements where (f element) is false or nil.</p> <p>user=&gt; (remove string? [1 \"turing\" :apple]) (1 :apple) Finally, one can group a sequence into chunks using partition, partition-all, or partition-by. For instance, one might group alternating values into pairs:</p> <p>user=&gt; (partition 2 [:cats 5 :bats 27 :crocodiles 0]) ((:cats 5) (:bats 27) (:crocodiles 0)) Or separate a series of numbers into negative and positive runs:</p> <p>(user=&gt; (partition-by neg? [1 2 3 2 1 -1 -2 -3 -2 -1 1 2]) ((1 2 3 2 1) (-1 -2 -3 -2 -1) (1 2)) Collapsing sequences After transforming a sequence, we often want to collapse it in some way; to derive some smaller value. For instance, we might want the number of times each element appears in a sequence:</p> <p>user=&gt; (frequencies [:meow :mrrrow :meow :meow]) {:meow 3, :mrrrow 1} Or to group elements by some function:</p> <p>user=&gt; (pprint (group-by :first [{:first \"Li\"    :last \"Zhou\"}                                  {:first \"Sarah\" :last \"Lee\"}                                  {:first \"Sarah\" :last \"Dunn\"}                                  {:first \"Li\"    :last \"O'Toole\"}])) {\"Li\"    [{:last \"Zhou\", :first \"Li\"}   {:last \"O'Toole\", :first \"Li\"}],  \"Sarah\" [{:last \"Lee\", :first \"Sarah\"} {:last \"Dunn\", :first \"Sarah\"}]} Here we\u2019ve taken a sequence of people with first and last names, and used the :first keyword (which can act as a function!) to look up those first names. group-by used that function to produce a map of first names to lists of people\u2013kind of like an index.</p> <p>In general, we want to combine elements together in some way, using a function. Where map treated each element independently, reducing a sequence requires that we bring some information along. The most general way to collapse a sequence is reduce.</p>"},{"location":"reference/sequences/#user-doc-reduce","title":"user=&gt; (doc reduce)","text":"<p>clojure.core/reduce ([f coll] [f val coll])   f should be a function of 2 arguments. If val is not supplied,   returns the result of applying f to the first 2 items in coll, then   applying f to that result and the 3rd item, etc. If coll contains no   items, f must accept no arguments as well, and reduce returns the   result of calling f with no arguments.  If coll has only 1 item, it   is returned and f is not called.  If val is supplied, returns the   result of applying f to val and the first item in coll, then   applying f to that result and the 2nd item, etc. If coll contains no   items, returns val and f is not called. That\u2019s a little complicated, so we\u2019ll start small. We need a function, f, which combines successive elements of the sequence. (f state element) will return the state for the next invocation of f. As f moves along the sequence, it carries some changing state with it. The final state is the return value of reduce.</p> <p>user=&gt; (reduce + [1 2 3 4]) 10 reduce begins by calling (+ 1 2), which yields the state 3. Then it calls (+ 3 3), which yields 6. Then (+ 6 4), which returns 10. We\u2019ve taken a function over two elements, and used it to combine all the elements. Mathematically, we could write:</p> <p>1 + 2 + 3 + 4     3 + 3 + 4         6 + 4            10 So another way to look at reduce is like sticking a function between each pair of elements. To see the reducing process in action, we can use reductions, which returns a sequence of all the intermediate states.</p> <p>user=&gt; (reductions + [1 2 3 4]) (1 3 6 10) Oftentimes we include a default state to start with. For instance, we could start with an empty set, and add each element to it as we go along:</p> <p>user=&gt; (reduce conj #{} [:a :b :b :b :a :a])</p>"},{"location":"reference/sequences/#a-b","title":"{:a :b}","text":"<p>Reducing elements into a collection has its own name: into. We can conj [key value] vectors into a map, for instance, or build up a list:</p> <p>user=&gt; (into {} [[:a 2] [:b 3]]) {:a 2, :b 3} user=&gt; (into (list) [1 2 3 4]) (4 3 2 1) Because elements added to a list appear at the beginning, not the end, this expression reverses the sequence. Vectors conj onto the end, so to emit the elements in order, using reduce, we might try:</p> <p>user=&gt; (reduce conj [] [1 2 3 4 5]) (reduce conj [] [1 2 3 4 5]) [1 2 3 4 5] Which brings up an interesting thought: this looks an awful lot like map. All that\u2019s missing is some kind of transformation applied to each element.</p> <p>(defn my-map [f coll]   (reduce (fn [output element]             (conj output (f element)))           []           coll)) user=&gt; (my-map inc [1 2 3 4]) [2 3 4 5] Huh. map is just a special kind of reduce. What about, say, take-while?</p> <p>(defn my-take-while [f coll]   (reduce (fn [out elem]             (if (f elem)               (conj out elem)               (reduced out)))           []           coll)) We\u2019re using a special function here, reduced, to indicate that we\u2019ve completed our reduction early and can skip the rest of the sequence.</p> <p>user=&gt; (my-take-while pos? [2 1 0 -1 0 1 2]) [2 1] reduce really is the uber function over sequences. Almost any operation on a sequence can be expressed in terms of a reduce\u2013though for various reasons, many of the Clojure sequence functions are not written this way. For instance, take-while is actually defined like so:</p> <p>user=&gt; (source take-while) (defn take-while   \"Returns a lazy sequence of successive items from coll while   (pred item) returns true. pred must be free of side-effects.\"   {:added \"1.0\"    :static true}   [pred coll]   (lazy-seq    (when-let [s (seq coll)]        (when (pred (first s))          (cons (first s) (take-while pred (rest s))))))) There\u2019s a few new pieces here, but the structure is essentially the same as our initial attempt at writing map. When the predicate matches the first element, cons the first element onto take-while, applied to the rest of the sequence. That lazy-seq construct allows Clojure to compute this sequence as required, instead of right away. It defers execution to a later time.</p> <p>Most of Clojure\u2019s sequence functions are lazy. They don\u2019t do anything until needed. For instance, we can increment every number from zero to infinity:</p> <p>user=&gt; (def infinite-sequence (map inc (iterate inc 0)))</p>"},{"location":"reference/sequences/#userinfinite-sequence","title":"'user/infinite-sequence","text":"<p>user=&gt; (realized? infinite-sequence) false That function returned immediately. Because it hasn\u2019t done any work yet, we say the sequence is unrealized. It doesn\u2019t increment any numbers at all until we ask for them:</p> <p>user=&gt; (take 10 infinite-sequence) (1 2 3 4 5 6 7 8 9 10) user=&gt; (realized? infinite-sequence) true Lazy sequences also remember their contents, once evaluated, for faster access.</p> <p>Putting it all together We\u2019ve seen how recursion generalizes a function over one thing into a function over many things, and discovered a rich landscape of recursive functions over sequences. Now let\u2019s use our knowledge of sequences to solve a more complex problem: find the sum of the products of consecutive pairs of the first 1000 odd integers.</p> <p>First, we\u2019ll need the integers. We can start with 0, and work our way up to infinity. To save time printing an infinite number of integers, we\u2019ll start with just the first 10.</p> <p>user=&gt; (take 10 (iterate inc 0)) (0 1 2 3 4 5 6 7 8 9) Now we need to find only the ones which are odd. Remember, filter pares down a sequence to only those elements which pass a test.</p> <p>user=&gt; (take 10 (filter odd? (iterate inc 0))) (1 3 5 7 9 11 13 15 17 19) For consecutive pairs, we want to take [1 3 5 7 ...] and find a sequence like ([1 3] [3 5] [5 7] ...). That sounds like a job for partition:</p> <p>user=&gt; (take 3 (partition 2 (filter odd? (iterate inc 0)))) ((1 3) (5 7) (9 11)) Not quite right\u2013this gave us non-overlapping pairs, but we wanted overlapping ones too. A quick check of (doc partition) reveals the step parameter:</p> <p>user=&gt; (take 3 (partition 2 1 (filter odd? (iterate inc 0)))) ((1 3) (3 5) (5 7)) Now we need to find the product for each pair. Given a pair, multiply the two pieces together\u2026 yes, that sounds like map:</p> <p>user=&gt; (take 3 (map (fn [pair] (* (first pair) (second pair)))                     (partition 2 1 (filter odd? (iterate inc 0))))) (3 15 35) Getting a bit unwieldy, isn\u2019t it? Only one final step: sum all those products. We\u2019ll adjust the take to include the first 1000, not the first 3, elements.</p> <p>user=&gt; (reduce +                (take 1000                      (map (fn [pair] (* (first pair) (second pair)))                           (partition 2 1                                     (filter odd?                                             (iterate inc 0))))) 1335333000 The sum of the first thousand products of consecutive pairs of the odd integers starting at 0. See how each part leads to the next? This expression looks a lot like the way we phrased the problem in English\u2013but both English and Lisp expressions are sort of backwards, in a way. The part that happens first appears deepest, last, in the expression. In a chain of reasoning like this, it\u2019d be nicer to write it in order.</p> <p>user=&gt; (-&gt;&gt; 0             (iterate inc)             (filter odd?)             (partition 2 1)             (map (fn [pair]                    (* (first pair) (second pair))))             (take 1000)             (reduce +)) 1335333000 Much easier to read: now everything flows in order, from top to bottom, and we\u2019ve flattened out the deeply nested expressions into a single level. This is how object-oriented languages structure their expressions: as a chain of function invocations, each acting on the previous value.</p> <p>But how is this possible? Which expression gets evaluated first? (take 1000) isn\u2019t even a valid call\u2013where\u2019s its second argument? How are any of these forms evaluated?</p> <p>What kind of arcane function is -&gt;&gt;?</p> <p>All these mysteries, and more, in Chapter 5: Macros.</p> <p>Problems Write a function to find out if a string is a palindrome\u2013that is, if it looks the same forwards and backwards. Find the number of \u2018c\u2019s in \u201cabracadabra\u201d. Write your own version of filter. Find the first 100 prime numbers: 2, 3, 5, 7, 11, 13, 17, \u2026.</p>"},{"location":"reference/threading-macros/","title":"Reference: Threading macros","text":"<p>Using the threading macro, the result of every function is passed onto the next function in the list.  This can be seen very clearly using ,,, to denote where the value is passed to the next function</p> <pre><code>(-&gt;\n \"project.clj\"\n slurp ,,,\n read-string ,,,\n (nth ,,, 2))\n</code></pre> <p>To make this really simple lets create a contrived example of the threading macro.  Here we use the <code>str</code> function to join strings together.  Each individual <code>str</code> function joins its own strings together, passing the resulting string as the first argument to the next function.</p> <pre><code>(-&gt;\n (str \"This\" \" \" \"is\" \" \")\n (str \"the\" \" \" \"threading\" \" \" \"macro\")\n (str \"in\" \" \" \"action.\"))\n</code></pre> <p>Output</p> <pre><code>;; =&gt; \"This is the threading macro in action\"\n</code></pre>"},{"location":"reference/threading-macros/#hintcommas-in-clojure-are-whitespace","title":"Hint::Commas in clojure are whitespace","text":"<p>Commas are simply ignored when the Clojure Reader parses code.  Commas are rarely used and only to help human readability of the code</p>"},{"location":"reference/threading-macros/#thread-last-macro","title":"Thread-last macro","text":"<p>Using the thread-last macro, -&gt;&gt;, the result of a function is passed as the last argument of the next function call.  So in another simple series of str function calls, our text comes out backwards.</p> <pre><code>(-&gt;&gt;  \" this\"\n (str \" is\")\n (str \" backwards\"))\n</code></pre>"},{"location":"reference/clojure-cli/","title":"Reference: Clojure CLI","text":"<p>A reference on using Clojure CLI and using community tools effectively.</p> <ul> <li>structure of the deps.edn configuration</li> <li>execution options</li> <li>Java Virtual Machine options</li> <li>defining custom aliases</li> <li>common aliases from practicalli/clojure-deps-edn project</li> </ul>"},{"location":"reference/clojure-cli/example-alias-definitions/","title":"Common alias definitions","text":""},{"location":"reference/clojure-cli/example-alias-definitions/#task-run-a-simple-terminal-repl","title":"Task: Run a simple terminal REPL","text":"<p><code>clojure</code> and <code>clj</code> (requires rlwrap) will run a REPL if given no other arguments.</p> <p>Running either command from the root directory of a project will merge the <code>deps.edn</code> configuration with <code>~/.clojure/deps.edn</code>.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-run-a-repl-with-additional-dependencies-and-paths","title":"Task: Run a REPL with additional dependencies and paths","text":"<p><code>clojure -M:alias</code> will run a repl if the alias does not contain a main namespace defined in <code>:main-opts</code>, e.g. <code>:main-opts [\"-m\" \"namespace.main\"]</code>.  The deps and path values are included from the alias.</p> <p>If the following alias is defined in the project <code>deps.edn</code> file</p> <pre><code>:env/dev\n{:extra-paths [\"resources\"]\n :extra-deps {com.h2database/h2 {:mvn/version \"1.4.200\"}}}\n</code></pre> <p><code>clojure -M:env/dev</code> will add <code>resources</code> directory to the path and the h2 database library to the dependencies, then runs a REPL.</p> <p>Including the <code>-r</code> option in the command line forces a REPL to run, even if a main namespace is provided via <code>:main-opts</code> or the command line.</p> <pre><code>clojure -r -M:alias1:alias2\n</code></pre> <p>The dependencies and paths will be merged from the alias from left to right, with each successive alias over-riding the value of any matching keys in the dependencies.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-create-a-new-project-from-template","title":"Task: Create a new project from template","text":"<p>The <code>clj-new</code> community tool can be used to create a Clojure / ClojureScript project, using a template to provide a project structure and example source code and tests.</p> <p>Using the <code>:main-opts</code> approach, an alias for <code>clj-new</code> would be defined as follows</p> <pre><code>  :project/new\n  {:extra-deps {seancorfield/clj-new {:mvn/version \"1.0.215\"}}\n   :main-opts  [\"-m\" \"clj-new.create\"]}\n</code></pre> <p>The <code>clj-new</code> tool can be run using the <code>-M</code> flag, passing the template and project names as arguments.</p> <p><code>clojure -M:project/new template-name project-domain/application-name</code></p> <p>To create a project as an application (to be run via the command line) for the practicalli domain with the application called banking-on-clojure</p> <pre><code>clojure -M:new app practicalli/banking-on-clojure\n</code></pre> <p>The latest version of the <code>clj-new</code> project also supports using the <code>-X</code> flag and default arguments.</p> <p>Adding the <code>:exec-fn</code> to the <code>clj-new</code> alias, the <code>-X</code> flag can be used instead of the <code>-M</code>.  Arguments are supplied as key/value pairs</p> <pre><code>  :project/new\n  {:extra-deps {seancorfield/clj-new {:mvn/version \"1.1.215\"}}\n   :exec-fn clj-new/create}\n</code></pre> <p>Use this alias with the <code>-X</code> flag</p> <pre><code>clojure -X:project/new :template template-name :name practicalli/banking-on-clojure\n</code></pre> <p>Default values can be added using the <code>:exec-args</code> key to the alias</p> <pre><code>:project/new\n{:extra-deps {seancorfield/clj-new {:mvn/version \"1.1.215\"}}\n :exec-fn clj-new.create\n :exec-args {:template lib :name practicalli/playground}}\n</code></pre> <p><code>clojure -M:project/new :name practicalli/awesome-webapp</code> will create a new project using the <code>{:template lib :name practicalli/awesome-webapp}</code> argument.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-specific-function","title":"Task: Executing a specific function","text":"<p>Clojure can run a specific function, useful for one off tasks or timed batch processing (via cron or similar tool) as well as complete applications.</p> <p>Arguments to the function are passed as a hash-map, defined in either an aliases <code>:exec-args</code> key or as key value pairs on the command line.  Command line key value pairs are merged with the <code>:exec-arg</code> hash-map, replacing the values from the command line if there are matching keys.</p> <p>Scenarios</p> <p><code>clojure -X namespace/fn</code> runs the function specified on the command line, passing an empty hash-map as an argument</p> <p><code>clojure -X:alias fn</code> runs the function if the <code>:ns-default</code> is set to the namespace that contains the function, otherwise \"Unqualified function can't be resolved: fn-name\" error is returned.</p> <p><code>clojure -X:alias</code> runs the function specified by <code>:exec-fn</code> in the alias.  The function must include its namespace or have that namespace defined in <code>:ns-default</code>. If <code>:exec-args</code> is defined in the alias, its value is passed to the function, otherwise an empty hash-map is passed to the function as an argument.</p> <p><code>clojure -X:alias namespace/fn</code> will run the function specified on the command line, over-riding <code>:exec-fn</code> if it is defined in the alias.  <code>:exec-args</code> will be passed to the command line function if defined in the alias. Dependencies and paths will be used from the alias. Assumption: the command line namespace also overrides the <code>:ns-default</code> value if set.</p> <p><code>clojure -X:alias :key1 val1 :key2 val2</code> will execute the function defined in <code>:exec-fn</code> and pass it the key value pairs from the command line as a hash map.  If the alias has <code>:exec-args</code> defined, command line args are merged into the <code>:exec-fn</code> hash-map, replacing the default values in <code>:exec-args</code> where keys match.</p> <p>Assuming there is an alias called <code>database/migrate</code> defined in the project <code>deps.edn</code></p> <pre><code>:database/migrate\n{:exec-fn practicalli.banking-on-clojure.database/migrate\n :exec-args {:db-type \"h2\" :database \"banking-on-clojure\"}}\n</code></pre> <p><code>clojure -X:database/migrate :database \"specs-repository\"</code> would merge the command line args with <code>:exec-args</code> to create the hash-map <code>{:db-type \"h2\" :database \"specs-repository\"}</code> which is passed to the <code>practicalli.banking-on-clojure.database/migrate</code> function as an argument.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-range-of-functions","title":"Task: Executing a range of functions","text":"<p><code>:ns-default</code> in an alias defines the namespace that contains the functions that could be executed.</p> <pre><code>{:aliases\n  {:project/run\n    {:ns-default practicalli/banking-on-clojure}}}\n</code></pre> <p>Specific functions from the namespace can be called via the command line</p> <pre><code>clojure -X:project/run migrate-db :db-type h2 :database banking-on-clojure\nclojure -X:project/run server-start :port 8080\n</code></pre>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-dry-run-or-prepare-for-ci-containers","title":"Task: Dry Run or Prepare for CI / Containers","text":"<p><code>clojure -P</code> will download the libraries defined in <code>:deps</code> in the project <code>deps.edn</code> and do nothing else.  Standard out shows downloading of dependencies not already cached locally, including name and versions and repository downloaded from.</p> <p></p> <p>Qualified namespaces required</p> <p>If an unqualified library name is used, e.g. <code>compojure</code>, then a warning is sent to the standard out.  Change the name of the library to be fully qualified e.g. <code>weavejester/compojure</code>.  Use the same name if there is no official qualified domain, e.g. <code>http-kit/http-kit</code></p> <p>The <code>-P</code> flag can be used to modify an existing command to ensure no execution takes place, ensuring a prepare only (dry run) action.</p> <p><code>clojure -P -M:alias-name</code> downloads the dependencies for the specific aliases and multiple aliases can be chained together, e.g. <code>clojure -P -M:dev/env:test-runner/kaocha</code></p> <p>The <code>-P</code> flag uses everything from an alias not related to execution.</p> <p>The classic way to download deps was to run <code>clojure -A:aliases -Spath</code>, where <code>-Spath</code> prevented execution of repl or main.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#run-a-clojure-application","title":"Run a Clojure application","text":"<p><code>clojure -m full.namespace.to.dash-main</code> calls the <code>-main</code> function from the given namespace. Arguments to the function are simply added to the end of the command line and passed to the <code>-main</code> function in the given namespace.</p> <p>The <code>-m</code> flag in the CLI tools pre-release returns a warning that <code>-M</code> should be used.</p> <p>Using <code>-M</code> and <code>-m</code> works, but seems redundant.  Using <code>-M</code> by itself runs the REPL.</p> <pre><code>clojure -M -m full.namespace.to.dash-main\n</code></pre> <p><code>-M</code> seems useful when including an alias with extra configuration (eg. <code>:extra-deps</code>, <code>:extra-paths</code>, <code>:main-opts</code>).  As <code>:main-opts</code> is no different to the <code>-m</code> option, creating an alias just to avoid the warning seems excessive.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#task-executing-a-project-using-edn-style-args","title":"Task: Executing a project - using Edn style args","text":"<p>Clojure CLI tools is encouraging a move to functions that take a hash-map for their arguments.  Passing arguments in as an edn data structure has more rigor than options and strings on the command line.</p> <p>The simplest form is to define an alias to run the project, specifying just the function to execute using <code>:exec-fn</code></p> <pre><code> :aliases\n {:project/run\n   {:exec-fn practicalli.banking-on-clojure/server-start}\n } ;; End of Aliases\n</code></pre> <p>Then the project can be run using this alias.</p> <pre><code>clojure -X:project/run\n</code></pre> <p>Arguments can be passed to the function as key/value pairs on the command line.</p> <pre><code>clojure -X:project/run  :port 8080 :host \"localhost\"\n</code></pre> <p><code>:exec-args</code> provides a way to define default arguments for the function, regardless of if it is defined in <code>;:exec-fn</code> or passed via the command line.</p> <p><code>:exec-args</code> defines a hash-map of arguments so the function must support taking a hash-map as an argument.</p> <p>A function may take variable args, especially if it is supporting both hash-maps and strings as options.</p> <pre><code> :aliases\n {:project/run\n   {:exec-fn fully.qualified/namespace\n    :exec-args {:default \"arguments\" :can-be-over-ridden-by \"command-line-args\"} }\n } ;; End of Aliases\n</code></pre> <p>Adding <code>:exec-args</code> to the <code>:run-project</code></p> <pre><code> :aliases\n {:project/run\n   {:exec-fn practicalli.banking-on-clojure/server-start\n    :exec-args {:port 8888 :host \"localhost\"}}\n } ;; End of Aliases\n</code></pre>"},{"location":"reference/clojure-cli/example-alias-definitions/#example-of-running-a-clojure-project-hello-world","title":"Example of running a Clojure project - hello-world","text":"<p>In this example I use the hello-world example from https://clojure.org/guides/deps_and_cli#_writing_a_program A project <code>deps.edn</code> file was created containing the dependency for clojure.java-time and the source code from that page copied into <code>src/hello.clj</code></p> <p><code>clojure -m</code> hello runs the project and returns the time from running the -main function. However this gives a warning:</p> <pre><code>WARNING: When invoking clojure.main, use -M\n</code></pre> <p><code>clojure -M</code> runs a REPL</p> <p><code>clojure -M -m hello</code> runs the project and returns the time.  But then I ask myself what is the purpose of -M</p> <p>Creating an alias to run the project seems an interesting idea, as I could also set default arguments.</p> <p>Adding an <code>:project-run</code> alias to the project <code>deps.edn</code> works when calling with clojure <code>-M:project-run</code></p> <pre><code> :aliases\n {:project-run {:main-opts [\"-m\" \"hello\"]}}\n</code></pre> <p>Changing the <code>:project-run</code> alias to use <code>:exec-fn</code> and a fully qualified function (-main by default) should work when calling with <code>clojure -X:project-run</code>.  :aliases  {:run-project {:exec-fn hello]}}</p> <p>However, the <code>hello-world</code> project has an unqualified function and cannot be resolved.</p> <p>Moving the source code to <code>src/practicalli/hello.clj</code> and calling <code>clojure -X:run-project</code> gives an execution error, <code>(ArityException)</code> as the <code>-main</code> function does not take any arguments, <code>(defn -main [] ,,,)</code>.</p> <p>Changing the <code>-main</code> function to <code>(defn -main [&amp; args] ,,,)</code> fixes the arity exception and calling <code>clojure -X:run-project</code> works.</p>"},{"location":"reference/clojure-cli/example-alias-definitions/#local-maven-install","title":"Local Maven install","text":"<p>Install a jar into the local Maven cache, typically <code>~/.m2/repository/</code> directory, organised by groupId</p> <pre><code>clojure -X:deps mvn-install :jar '\"/path/to.jar\"'\n</code></pre> <p>edn strings must be in double quotes, and then single-quoted for the shell</p> <p><code>mvn-install</code> uses the <code>.pom</code> file contained in the jar (if it exists) to determine the groupId, artifactId, and version coordinates to use when the jar is installed.</p> <p>The <code>.pom</code> file can also be specified using the  <code>:pom</code> argument.</p> <p>The install argmap takes the following options:</p> key Required Description <code>:jar</code> required path to the jar file to install <code>:pom</code> optional path to .pom file (if .jar file does not contain .pom) <code>:lib</code> optional qualified symbol e.g <code>my.org/lib</code> <code>:version</code> optional Version number of library (string type) <code>:classifier</code> optional (string type) <code>:local-repo</code> optional path to local repo (default = ~/.m2/repository)"},{"location":"reference/clojure-cli/jvm-options/","title":"Reference: Clojure CLI JVM Options","text":"<p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p> <p>Java Virtual Machine options can be passed using the Clojure CLI, either via the <code>-J</code> command line flag or <code>:jvm-opts</code> in a <code>deps.edn</code> alias.</p> <p>Java Virtual Machine configuration and reporting</p> <p>Java Virtual Machine section covers commonly used options, reporting JVM metrics and optimisation of the JVM process.</p>"},{"location":"reference/clojure-cli/jvm-options/#clojure-cli-command-line-options","title":"Clojure CLI command line options","text":"<p>Clojure CLI <code>-J</code> flag passes configuration options to the JVM. When there are multiple, each must be prefixed with <code>-J</code>.</p> <pre><code>clojure -J-XX:+UnlockDiagnosticVMOptions -J\u2011XX:NativeMemoryTracking=summary -J\u2011XX:+PrintNMTStatistics\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#clojure-cli-depsedn-configuration","title":"Clojure CLI deps.edn configuration","text":"<p><code>:jvm-opts</code> key in an alias adds JVM options to Clojure CLI deps.edn configuration.  The <code>:jvm-opts</code> key has a value that is a collection of string JVM options <code>[\"-Xms2048m\" \"-Xmx4096\"]</code></p> <p>Alias to set a large heap size</p> <pre><code>:jvm/heap-max-2g {:jvm-opts [\"-Xmx2G\"]}\n</code></pre> <p>Report a full breakdown of the HotSpot JVM\u2019s memory usage upon exit using the following option combination:</p> <pre><code>:jvm/report {:jvm-opts [\"-XX:+UnlockDiagnosticVMOptions\"\n                        \"\u2011XX:NativeMemoryTracking=summary\"\n                        \"\u2011XX:+PrintNMTStatistics\"]}\n</code></pre> <p>Add a Java module</p> <pre><code>:jvm/xml-bind {:jvm-opts [\"\u2013add-modules java.xml.bind\"]}\n</code></pre> <p>Ignoring unrecognised options</p> <pre><code>:jvm-opts [\"-XX:+IgnoreUnrecognizedVMOptions\"]\n</code></pre> <p>The aliases can be used with the Clojure CLI execution options: <code>-A</code> (for built-in REPL invocation), <code>-X</code> and <code>-T</code> (for clojure.exec function execution), or <code>-M</code> (for clojure.main execution).</p> <p><code>-J</code> JVM options specified on the command line are concatenated after the alias options</p>"},{"location":"reference/clojure-cli/jvm-options/#calling-a-clojure-uberjar","title":"Calling A Clojure Uberjar","text":"<p>JVM options must be specified when calling an uberjar with the <code>java</code> command, <code>:jvm-opts</code> in the project <code>deps.edn</code> are not used with the <code>java</code> command</p> <pre><code>java -jar project-uberjar.jar -J...\n</code></pre> <p>Use <code>JDK_JAVA_OPTIONS</code> to define JVM options</p> <p><code>JDK_JAVA_OPTIONS</code> environment variable is used to define options that are used whenever the <code>java</code> command is called, greatly simplifying <code>java</code> commands.</p> <p>The <code>JDK_JAVA_OPTIONS</code> environment variable can be used with deployment systems and passed to container environments to simplify adjustment of resources used by the JVM process.</p>"},{"location":"reference/clojure-cli/jvm-options/#clojure-related-jvm-options","title":"Clojure related JVM options","text":"<p>Specify options or system properties to set up the Clojure service</p> <p><code>-Dclojure.compiler.disable-locals-clearing=true</code> - make more info available to debuggers</p> <p><code>-Dclojure.main.report=stderr</code> - print stack traces to standard error instead of saving to file, useful if process failing on startup</p> <p><code>-Dclojure.spec.skip-macros=false</code> - skip spec checks against macro forms</p>"},{"location":"reference/clojure-cli/jvm-options/#memory-management","title":"Memory Management","text":"<p><code>-XX:CompressedClassSpaceSize=3G</code> - prevent a specific type of OOMs</p> <p><code>-XX:MaxJavaStackTraceDepth=1000000</code> - prevents trivial Stack Overflow errors</p> <p><code>-Xmx24G</code> - set high maximum heap, preventing certain types of Out Of Memory errors (ideally high memory usage should be profiled if cause not known)</p> <p><code>-Xss6144k</code> - increase stack size x6 to prevent Stack Overflow errors</p> <p>The current default can be found with <code>java -XX:+PrintFlagsFinal -version 2&gt;/dev/null | grep \"intx ThreadStackSize\"</code></p> <p><code>-Xms6G</code> - Set minimum memory that is equal or greater than memory used by a running REPL, to improve performance</p> <p><code>-Xmx1G</code> - limit maximum heap allocation so a process can never use more memory, useful for environments with limited memory resources</p> <pre><code>:jvm/mem-max1g {:jvm-opts [\"-Xmx1G\"]}\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#container-memory-management","title":"Container Memory Management","text":"<p><code>JDK_JAVA_OPTIONS</code> environment variable should be used for setting JVM options within a container or in the provisioning service (e.g. Kubernettes / Argo CD) that deploys containers.</p> <p>Use JVM options that optimise running in a container</p> <ul> <li> <p><code>-XshowSettings:system</code> to output the resources the JVM believes it has access too, a very simple diagnostic tool to include</p> </li> <li> <p><code>-XX:+UseContainerSupport</code> instruct the JVM that it is running in a container environment, disabling the checks the JVM would otherwise carry out to determine if it was running in a container.  Can save a very small amount of start up time, though mainly used to ensure the JVM knows its in a container.</p> </li> <li> <p><code>-XX:MaxRAMPercentage=90</code> to set a relative maximum percentage of heap to use, based on the memory available from the host, e.g. <code>-XX:MaxRAMPercentage=80</code> will use a heap size of 80% of the available host memory</p> </li> </ul>"},{"location":"reference/clojure-cli/jvm-options/#dockerfile-example-with-jdk_java_options-environment-variable","title":"Dockerfile example with JDK_JAVA_OPTIONS environment variable","text":"<p>In this <code>Dockerfile</code> excerpt the <code>JDK_JAVA_OPTIONS</code> environment variable is used to print out the resources the JVM believes it has access to at startup. The JVM is instructed that it is running in a container environment and should use a maximum 90% heap size of the hosts memory resource.</p> <pre><code>ENV JDK_JAVA_OPTIONS \"-XshowSettings:system -XX:+UseContainerSupport -XX:MaxRAMPercentage=90\"\nCMD [\"java\", \"-jar\", \"/opt/practicalli-service.jar\"]\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#low-latency-systems","title":"Low latency systems","text":"<p>For systems that require very low latency, use the Z Garbage collector</p> <pre><code>\"-XX:+UnlockExperimentalVMOptions -XX:+UseZGC\"\n</code></pre>"},{"location":"reference/clojure-cli/jvm-options/#stack-traces","title":"Stack traces","text":"<p><code>-XX:+TieredCompilation</code> - enable tiered compilation to support accurate bench-marking (increases startup time)</p> <p><code>-XX:-OmitStackTraceInFastThrow</code> - don't elide stack traces</p>"},{"location":"reference/clojure-cli/jvm-options/#startup-options","title":"Startup options","text":"<p><code>-Xverify:none</code> option reduces startup time of the JVM by skipping verification process</p> <pre><code>\"-Xverify:none\"\n</code></pre> <p>The verification process is a valuable check, especially for code that has not been run before.  So the code should be run through the verification process before deploying to production.</p>"},{"location":"reference/clojure-cli/jvm-options/#benchmark-options","title":"Benchmark options","text":"<p>Enable various optimizations, for guaranteeing accurate benchmarking (at the cost of slower startup):</p> <p><code>\"-server\"</code></p>"},{"location":"reference/clojure-cli/jvm-options/#graphical-ui-related-options","title":"Graphical UI related options","text":"<p><code>-Djava.awt.headless=true</code> - disable all UI features for disabling the clipboard for personal security:</p> <p><code>-Dapple.awt.UIElement=true</code> - remove icon from the MacOSX Dock</p> <p><code>-Dclash.dev.expound=true</code> - ?</p>"},{"location":"reference/clojure-cli/jvm-options/#garbage-collection","title":"Garbage Collection","text":"<p>Setup GC with short STW pauses which can be relevant for very high web server workloads</p> <pre><code>:jvm/g1gc\n{:jvm-opts [\"-XX:+UseG1GC\"\n            \"-XX:MaxGCPauseMillis=200\"\n            \"-XX:ParallelGCThreads=20\"\n            \"-XX:ConcGCThreads=5\"\n            \"-XX:InitiatingHeapOccupancyPercent=70\"]}\n</code></pre> <ul> <li>Source: Tuning Garbage Collection with Oracle JDK</li> </ul>"},{"location":"reference/clojure-cli/jvm-options/#view-jvm-options-of-a-running-jvm-process","title":"View JVM options of a running JVM process","text":"<p>Use a JMX client, e.g. VisualVM</p> <p><code>jcmd pid VM.system_properties</code> or <code>jcmd pid VM.flags</code> using <code>jcmd -l</code> to get the pid of the JVM process</p> <p>On Linux <code>ps -ef | grep java</code> which includes the options to run the JVM process, <code>ps -auxww</code> to show long arguments</p> <p>Getting the parameters of a running JVM</p>"},{"location":"reference/clojure-cli/jvm-options/#references","title":"References","text":"<p>JVM Options cheatsheet - JRebel</p>"},{"location":"reference/clojure-svg/","title":"Clojure Scalable Vector Graphics - SVG","text":"<p>Scalable Vector Graphics, SVG, is an image format for two-dimensional (2D) graphics.</p> <p>An SVG image uses data to describe how to draw an image, ensuring that images can shrink and scale easily and retain a high quality image.  As images are formed from data, shapes can easily be combined or intersected to form new shapes.  Using a data format also means SVG images can be created from code and therefore animated.</p> <p>Raster image formats like gif, jpeg and png use a grid of squares called pixels to define an image (also known as a bitmap). Each pixel has a colour and position in an image.  When zooming into an image the pixels grow larger distorting the sharpness of an image, referred to as pixelation, .Multiple versions of raster images are often created at different resolutions to reduce the loss of quality when viewed at different sizes.</p>"},{"location":"reference/clojure-svg/#hintwork-in-progress","title":"Hint::Work in progress","text":""},{"location":"reference/clojure-svg/#concepts","title":"Concepts","text":"<ul> <li>viewbox</li> <li>style - border, background, width, height, stoke, fill, draw (path)</li> <li>shapes - circle, path</li> </ul>"},{"location":"reference/clojure-svg/#viewbox","title":"Viewbox","text":"<p>A viewbox defines a co-ordinate system for the image. Defining a size for the viewbox defining a frame for the image where positions are relative to that frame, irrespective of the size of the image or how that image is scaled.</p> <p>A viewbox size should be selected to make the image as simple as possible to define within itself.</p> <p>Example: tictactoe O's and X's and the grid that represents the board.</p> <p>tictactoe O's and X's and the grid that represents the board</p>"},{"location":"reference/clojure-svg/#related-projects","title":"Related projects","text":"<ul> <li>TicTacToe with ClojureScript, Reagent and SVG</li> <li>System monitoring</li> <li>Practicalli SVG examples library</li> <li>Programming SVG with Clojure (TODO)</li> </ul>"},{"location":"reference/clojure-svg/#references","title":"References","text":"<ul> <li>SVG: Scalable Vector Graphics - Mozilla Developer network</li> </ul>"},{"location":"reference/clojure-syntax/assigning-names/","title":"Assigning Names","text":"<p>If we have to type the same values over and over, it would be very hard to write a program. What we need are names for values, so we can refer to them in a way we can remember. We do that using <code>def</code>.</p> <pre><code>(def mangoes 3)\n(def oranges 5)\n(+ mangoes oranges)\n</code></pre> <p>When you assign a name to a value, that name is called a symbol. You can assign more than simple values to symbols. Try the following:</p> <pre><code>(def fruit (+ mangoes oranges))\n(def average-fruit-amount (/ fruit 2))\naverage-fruit-amount\n</code></pre> <p>Look at the last line, and see how we can use symbols by themselves to refer to a value.</p> <p>Note Take the Clojure syntax you have learnt to far and write a metric/imperial converter</p> <p>Take your height in feet and inches and convert it to inches using arithmetic in Clojure.</p> <p>Then convert that to centimeters. There are 2.54 centimeters in an inch.</p> <p>Lastly, ask two people near you for their height in centimeters. Find the average of your heights.</p> <p>Note Bonus: Convert that average back to feet and inches. The feet and the inches will be separate numbers. <code>(quot x y)</code> will give you the whole number part when dividing two numbers. <code>(mod x y)</code> will give you the remainder when dividing two numbers.</p>"},{"location":"reference/clojure-syntax/code-documentation/","title":"Code documentation","text":"<p>Clojure functions are documented by adding a string to the function definition, after the function name.  This is referred to as the doc string.</p> <pre><code>(defn example-function\n  \"This is the documentation for this function, referred to as a doc string\"\n  [arguments]\n  (str \"some behaviour\"))\n</code></pre> <p><code>def</code> bindings can also be documented to provide context to the data the name is bound to.</p> <pre><code>(def weather-data\n  \"Data set for weather across the major capitals of Europe\"\n  [{:date \"2020-05-015\" :city \"Berlin\" :temperature-max 24 :temperature-min 13 :rainfall 1}\n   {:date \"2020-05-015\" :city \"Amsterdam\" :temperature-max 25 :temperature-min 14 :rainfall 0}])\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#write-easily-understandable-docstrings","title":"Write easily understandable docstrings","text":"<p>Practically recommends including specific details of the arguments passed to a function and the expected return type.  Including this at the end of the docstring makes that information very quick to find.</p> <pre><code>  \"Geographic visualization data set generator\n\n  Arguments:\n  - combined data set of GeoJSON and Cases\n  - maximum integer value for scale\n  Returns:\n  - Oz view hash-map\"\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#reading-source-code","title":"Reading source code","text":"<p><code>clojure.repl/source</code> will show the source code of a given function, which can be a valuable way to understand the function.  Reading function source code also provides ideas when writing custom Clojure code.</p> <p>Reading the source code for <code>clojure.core</code> functions is a good way to learn those functions, although some functions have been optimised for performance and are harder to follow.</p> <p>Source code for clojure.core is available online and is also linked to from the function descriptions on clojuredocs.org.</p>"},{"location":"reference/clojure-syntax/code-documentation/#writing-your-own-documentation","title":"Writing your own documentation","text":"<p>Writing good documentation for your own functions take practice which pays off in the long run.</p> <pre><code>()\n</code></pre> <pre><code>(defn my-function\n  \"I should practice writing clear and meaningful documentation for my functions.\n  Arguments: brief description of arguments\"\n  [arguments]\n  (str \"I should write pure functions where ever possible. \"\n       \"Each function should have a specific purpose. \"\n       \"A function should be clean and easy to read.\"))\n</code></pre>"},{"location":"reference/clojure-syntax/code-documentation/#notedefine-your-own-function","title":"Note::Define your own function","text":"<p>Practice writing a meaningful documentation in the doc string</p>"},{"location":"reference/clojure-syntax/comments/","title":"Comments","text":"<p>As well as the classic line comments, Clojure also can comment specific parts of the code structure, even when it run over multiple lines.</p> <p><code>;;</code> to comment a whole line and <code>;</code> to add a comment after the start of a line</p> <p><code>(comment )</code> wraps forms and returns <code>nil</code> when evaluated, referred to as rich comments</p> <p><code>#_</code> to ignore the next form as if it has not been written, commonly used for debugging</p>"},{"location":"reference/clojure-syntax/comments/#line-comments","title":"Line comments","text":"<p>Add general documentation for a namespace, such as a comment header that describes the overall purpose of a namespace.</p> <p>Separate a namespace into logical sections to aid navigation and help identify opportunities to refactor a namespace as it grows.</p>"},{"location":"reference/clojure-syntax/comments/#comment-function","title":"comment function","text":"<p>The <code>(comment ,,,)</code> function is used to included code that is only run by the developer directly.</p> <pre><code>(comment (map + [1 2 3] [1 2 3]))\n</code></pre> <p>The <code>comment</code> function returns <code>nil</code> so its advised not to use it inside another form.  For example:</p> <pre><code>(map + [1 2 3] (comment [1 2 3])) ; nil will be passed to map as the third argument\n</code></pre> <p>This will fail as it tries to use the <code>+</code> function to add <code>1</code> to <code>nil</code></p> <p>The <code>#_</code> is the appropriate comment style for this example</p>"},{"location":"reference/clojure-syntax/comments/#rich-comment","title":"Rich comment","text":"<p>The <code>comment</code> expression is referred to a a rich comment, as it is often used to evaluate expressions it contains as part of a REPL driven development workflow.</p> <p>Unlike line comments, forms inside a comment block can be evaluated in a Clojure aware editor to help the developer work with a project.</p> <p>Rich comment are useful for rapidly iterating over different design decisions by including the same function but with different implementations. Hide clj-kondo linter](/clojure-cli/install/install-clojure.html#clj-kondo-static-analyser--linter) warnings for redefined vars (<code>def</code>, <code>defn</code>) when using this approach.</p> <pre><code>;; Rich comment block with redefined vars ignored\n#_{:clj-kondo/ignore [:redefined-var]}\n(comment\n\n  ) ;; End of rich comment block\n</code></pre> <p>The expressions can represent example function for using the project, such as starting/restarting the system, updating the database, etc.</p> <p></p> <p>Expressions in rich comment blocks can also represent how to use a namespace API, providing examples of arguments to supply to further convey meaning to the code.</p> <p>These rich comments make a project more accessible and easier to use.</p> <p>The \"Rich\" in the name also refers to Rich Hickey, the author and benevolent leader of the Clojure language.</p>"},{"location":"reference/clojure-syntax/comments/#comment-forms-with-the-comment-reader-macro","title":"Comment forms with the comment reader macro","text":"<p><code>#_</code> is the comment reader macro that instructs the Clojure reader to completely ignore the next form, as if it had never been written.</p> <p>No value is returned, so this comment is safe to use within an expression.</p> <p>You can place <code>#_</code> before the start of a form and everything inside that form will be commented</p> <pre><code>#_(def my-data [1 2 3 4 5])\n</code></pre> <p><code>#_</code> will comment forms that span multiple lines, for example function definitions</p> <pre><code>#_(defn my-function\n        [args]\n        (str \"I am an experiment, so not always needed\"))\n</code></pre> <p><code>#_</code> can also be put on the line(s) before the Clojure form, which can make your code more readable and keep alignment of your code consistent.</p>"},{"location":"reference/clojure-syntax/comments/#debugging-with-comment-macro","title":"debugging with comment macro","text":"<p>As the comment macro can be used without returning a value, it can safely be added to code to help with debugging.</p> <p>This code example finds the most common word in the text of a book.  Most of the lines of code in the threading macro have been commented to discover what the non-commented code does.</p> <p>As each expression in the threading macros is understood, by looking at its results, comments can be removed to understand more of the code.</p> <pre><code>(defn most-common-words [book]\n  (-&gt;&gt; book\n       (re-seq #\"[a-zA-Z0-9|']+\" ,,,)\n       #_(map #(clojure.string/lower-case %))\n       #_(remove common-english-words)\n       #_frequencies\n       #_(sort-by val)\n       #_reverse\n       ))\n</code></pre> <p>This is an effective way to deconstruct parts of a larger Clojure expression.</p> <p>Watch episode #13 of Practicalli Clojure study group to see this in practice.</p>"},{"location":"reference/clojure-syntax/comments/#comment-nested-forms","title":"comment nested forms","text":"<p><code>#_</code> tells the reader to ignore the next form, it is therefore never evaluated and neither is the <code>#_</code>.  This means that <code>#_</code> can be used inside a nested form to comment just a part of the expression</p> <p>In this example the third vector of values is not read by the Clojure reader and therefore is not passed as an argument to <code>+</code> function by <code>map</code></p> <p><code>(map + [1 2 3] [4 5 6] #_[7 8 9])</code></p>"},{"location":"reference/clojure-syntax/comments/#stacking-comments","title":"Stacking comments","text":"<p>The comment reader macro has the ability to stack these comments on forms, so using <code>#_#_</code> will comment out two successive forms.</p> <p>In a <code>let</code> form we can comment out a name binding that is causing problems.  As the name and value are both forms, then we use a stacked <code>#_</code> to comment both out. We also do the same in the body of the let, so as to not include the evaluation of the string or <code>name2</code> local name in the <code>str</code> form.</p> <pre><code>(let [name1 \"value\"\n       #_#_name2 \"another-value]\n   (str \"First name is: \" name1 #_#_\" second name is: \" name2\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/","title":"Control Flow","text":"<p>The following section of functions gives examples of simple control flow.  As you gain more experience with Clojure, you will discover more functional ways to achieve the same (or better) results.</p> <p>Hint Although these functions may seem similar to other non-functional languages, there are subtle differences</p>"},{"location":"reference/clojure-syntax/control-flow/#if","title":"If","text":"<p>Using the <code>if</code> function you can test if an expression evaluates to true.  If it is true, the first value is returned, if its false the second value is returned.</p> <p>Here is a simple example to see if one number is bigger that another</p> <pre><code>(if (&gt; 3 2)\n  \"Higher\"\n  \"Lower\")\n\n=&gt; \"Higher\"\n</code></pre> <p>Here is an example of an condition inside an anonymous function.</p> <pre><code>(defn even-number [number]\n  (if (odd? number)\n    (inc number)\n    number))\n\n(even-number 41)\n;; =&gt; 42\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#when","title":"When","text":"<p>When a condition is true, then return the value of evaluating the next expression.  If the condition is false, then return <code>nil</code></p> <pre><code>    (when (&gt; 3 2)\n      \"Higher\")\n\n=&gt; \"Higher\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#case","title":"Case","text":"<p>When one of these things is true, do this, else default</p> <pre><code>(case (inc 3)\n  1 \"Not even close\"\n  2 \"I wish I was that young\"\n  3 \"That was my previous value\"\n  4 \"You sunk my battleship\"\n  \"I dont think you understood the question\")\n\n=&gt; \"You sunk my battleship\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#cond","title":"Cond","text":"<p>Return the associated value of the first condition that is true, or return the default value specified by <code>:otherwise</code></p> <pre><code>(cond\n  (= 7 (inc 2)) \"(inc 2) is not 7, so this condition is false\"\n  (= 16 (* 8 2)) \"This is the first correct condition so its associated expression is returned\"\n  (zero? (- (* 8 8) 64)) \"This is true but not returned as a previous condition is true\"\n  :otherwise \"None of the above are true\")\n\n;; =&gt; \"This is the first correct condition so its associated expression is returned\"\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#for","title":"For","text":"<p>Using the <code>for</code> function you can Iterate through the values in a collection and evaluate each value in tern with  with a condition, using either <code>:when</code> or <code>:while</code>.</p> <pre><code>(for [x (range 10) :when (odd? x)] x)\n\n(for [x (range 10) :while (even? x)] x)\n\n(for [x (range 10)\n      y (range 10)]\n  [x y])\n</code></pre>"},{"location":"reference/clojure-syntax/control-flow/#while","title":"While","text":"<p>Do something while the condition is true</p> <pre><code>(while (condition)\n  (do something))\n</code></pre> <p>Here is a simple while example that uses a (mutable) counter and prints out the results to the repl window.</p> <pre><code>;; create a counter using a mutable counter\n(def counter (atom 10))\n\n;; While the counter is positive (is a number greater than zero), print out the current value of the counter.\n(while (pos? @counter)\n  (do\n    (println @counter)\n    (swap! counter dec)))\n</code></pre> <p>This example uses mutable state and causes a side effect by printing to the repl.  Both these kinds of things are typically kept to a minimum in Clojure.</p> <p>TODO An alternative would be to use use the iteration over a collection to control the while condition</p>"},{"location":"reference/clojure-syntax/defining-functions/","title":"Defining Functions","text":"<p><code>clojure.core/defn</code> defines a custom function that can be called from anywhere in the current namespace by just using the name.  A defined function can be called from where ever its namespace is required in other namespaces.</p> <p>Here is a simple function definition that takes a number and divides it by two</p> <pre><code>    (defn half-a-number\n      \"Divide a given number by 2\"\n      [number]\n      (/ number 2))\n</code></pre> <p>Once you have defined a function, you can call it by using the function name as the first element of a list, <code>()</code>.  Any other elements in the list are arguments passed to the function.</p> <pre><code>    (half-a-number 4)\n</code></pre>"},{"location":"reference/clojure-syntax/defining-functions/#understanding-the-defn-syntax","title":"Understanding the <code>defn</code> syntax","text":"<p>The standard form of <code>defn</code>:</p> <pre><code>(defn name doc-string? attr-map? [params*] prepost-map? body)\n</code></pre> <p>name is a symbol used to call the function.</p> <p>doc-string? is an optional string used to provide a meaningful description of the function definition.  This description is the living documentation of the function and can be accessed via `clojure.repl/doc** functions and Clojure aware editors.</p> <p>attr-map? is an optional map for pre-conditions for a function.</p> <p>[params*] is a zero or more vector of symbols that represent the arguments passed to a function.  The number of symbols defined must be matched when calling the function, or an exception will occur.</p> <p>prepost-map? an optional map for post-conditions for a function.</p> <p>body is the algorithm that will evaluate when the function is called.</p> <p>There is a second form of the <code>defn</code> function, one which responds differently based on the number of arguments used to call the function (polymorphic).</p> <pre><code>(defn name doc-string? attr-map?\n  ([params*] prepost-map? body) + attr-map?)\n</code></pre> <p>Thinking Functionally - Polymorphism has examples of using defn to define polymorphic functions</p>"},{"location":"reference/clojure-syntax/defining-functions/#breaking-down-the-defn-syntax","title":"Breaking down the defn syntax","text":"<p>The syntax <code>defn</code> is what we call a macro, it is a simpler way to write clojure code that does the same thing.</p> <p>You can think of defining a function with <code>defn</code> as two steps</p> <ol> <li>Give the function a name - using the <code>def</code> syntax</li> <li>Define the functions behaviour and arguments it takes - using the <code>fn</code> syntax</li> </ol> <p>Here is the same function if you typed it out in full</p> <pre><code>    (def half-a-number\n      (fn [number]\n        (/ number 2)))\n</code></pre>"},{"location":"reference/clojure-syntax/defining-functions/#hintmacroexpand-functions","title":"Hint::Macroexpand functions","text":"<p>The <code>macroexpand-1</code> function takes an expression that includes one or more macros and returns the expanded version of Clojure code. The <code>macroexpand-all</code> will also expand macros into Clojure code, doing so recursively for all macros it finds.</p> <p>Clojure editors also provide evaluation functions that will macroexpand.</p>"},{"location":"reference/clojure-syntax/global-definitions/","title":"Global definitions","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/java-interop/","title":"Java Interoperability","text":"<p>Clojure provides very clear and simple syntax for Java interoperability, using the following functions</p> <ul> <li><code>import</code> - add functions from the Java library into the current namespace</li> <li><code>new</code> - create a new Java object</li> <li><code>.</code> - is the short form of the <code>new</code> function</li> </ul> <p>As Clojure is hosted on the Java Virtual Machine (JVM), its very easy to include libraries from any other languages that runs on the JVM, for example Java, Groovy, Scala, Jython, JRuby, Jaskell, etc.</p> <p>The Leiningen build tool provides a simple way to include libraries as dependencies, using the <code>:dependencies</code> section of the <code>project.clj</code> file. Any library published to Maven Central is available for download by Leiningen, as both Maven Central and Clojars.org repositories are used by default.</p> <p>java.lang included</p> <p>Clojure projects and REPL environments include the <code>java.lang</code> library automatically.  Any methods from that library can be used without having to <code>import</code> them or include any dependencies</p>"},{"location":"reference/clojure-syntax/java-interop/#the-syntax","title":"The syntax","text":"<p>Its very easy to call Java methods and objects from clojure using the following syntax</p> <pre><code>(.instanceMember instance args*)\n(.instanceMember Classname args*)\n(.-instanceField instance)\n(Classname/staticMethod args*)\nClassname/staticField\n</code></pre> <p>Note Use the instanceMember .toUpperCase to convert a string from lower case to upper case</p> <p>Call the <code>.toUpperCase</code> function on any string you like, for example</p> <pre><code>(.toUpperCase \"I was low, but now I'm up\")\n</code></pre> <p>The string passed as an argument should now be all uppercase: \"I WAS LOW, BUT NOW I'M UP\"</p> <p>Note Use the staticField <code>Math/PI</code> to return the approximate value of Pi</p> <p>You can treat any static field like any name defined in your Clojure code, so when evaluated the static field simply returns the value it represents</p> <p>In this case the <code>Math/PI</code> static field simply returns the approximate value of Pi that fits into a java.lang.Double type.</p> <pre><code>Math/PI\n-&gt; 3.141592653589793\n</code></pre>"},{"location":"reference/clojure-syntax/java-interop/#getting-the-java-environment","title":"Getting the Java environment","text":"<p>Earlier we used Clojure functions to find information about our environment.  We can also used the <code>getProperty()</code> method from the <code>java.lang.System</code> object to ask for the java version and jvm name.</p> <p>Note Get version of Java &amp; the JVM, returning those values as a meaningful string.  Then get the version of the Clojure project</p> <pre><code>(str \"You are running Java version \" (System/getProperty \"java.version\") \"with the JVM\" (System/getProperty \"java.vm.name\"))\n\n(str \"Latest project version: \" (System/getProperty \"playground.version\"))\n</code></pre> <p>Note Use <code>System/getenv</code> to return your system's environment variables as a map</p> <pre><code>(System/getenv)\n</code></pre> <p></p> <p>You may notice that this is a map data structure that we return, so we can use use destructuring or the maps behaviour itself to pull out information.</p> <p>Hint A full list of properties can be seen in the getProperty() documentation</p> <p>There are more examples of Java Interoperability in the next few sections.</p>"},{"location":"reference/clojure-syntax/local-bindings/","title":"Local Bindings","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/more-java-fun/","title":"More Java fun","text":"<p>Lets try some more examples to show how easy it is to use Java methods and objects.  Remember that everything in java.lang is available in your Clojure project by default</p>"},{"location":"reference/clojure-syntax/more-java-fun/#returning-specific-types","title":"Returning specific types","text":"<p>Clojure has types, after all it runs on the JVM and included <code>java.lang</code> library in ever project.  Types are inferred at runtime, saving you the need to design types yourself.</p> <p>Sometimes you want to ensure a value is of a particular type and you can use Java to do this.</p> <p>Note Return a string value as an integer</p> <p>When you create a new <code>java.lang.Integer</code> object you can provide a default value by passing either a number or string type.</p> <pre><code>(new Integer \"123\")\n\n;; Or the more common short-hand forms\n\n(Integer. \"123\")\n</code></pre> <p>This is the equivalent to the Java code:</p> <pre><code> Integer myInt = new Integer(\"123\");\n</code></pre> <p>The <code>.</code> function essentially instantiates a new object from the class, in this case <code>Integer</code>, passing any arguments to its constructor.</p> <p>Hint Example: converting the port number read from an environment variable as a string which needs to be passed to the Jetty server as a number.  See the Clojure Webapp workshop an example.</p> <p>More on types in the section a quick look at types</p> <p>fixme The following is work in progress</p>"},{"location":"reference/clojure-syntax/more-java-fun/#using-java-date","title":"Using Java date","text":"<p>Note Use <code>java.util.Date</code> to explore date and time</p> <pre><code>(import java.util.Date)\n\n(Date.)\n\n(def now (Date.))\n\n(str now)\n</code></pre> <p></p> <p>Its easy to create a local reference to a Java Date object instance and then call methods on that date object</p> <pre><code>(let [date (java.util.Date.)] (.getHours date))\n</code></pre> <p>Or using the threading macro, we can make the code a little clearer</p> <pre><code>(-&gt;\n   (java.util.Date.)\n   (.getHours))\n</code></pre>"},{"location":"reference/clojure-syntax/more-java-fun/#its-joda-time","title":"Its Joda Time","text":"<p><code>clj-time</code> is a Clojure wrapper for Joda time.  As this is an external library, you need to add it to your project.clj file as a dependency.  To find the latest version, check the clj-time library on Clojars.org</p> <p>Note Add the clj-time dependency to your project (restart needed), require the clj-time library in your code and use the functions <code>now</code>, <code>formatters</code>&amp; <code>unparse</code></p> <pre><code>(require '[clj-time.core :as time])\n(require '[clj-time.format :as time-format])\n\n(time/now)\n\n;; ISO 8601 UTC format\n(def time-formatter (time-format/formatters :basic-date-time))\n(time-format/unparse custom-formatter (date-time 2010 10 3))\n</code></pre>"},{"location":"reference/clojure-syntax/more-java-fun/#swing-coding","title":"Swing coding","text":"<p>Swing GUI coding in Java feels quite messy to me, however using Swing in Clojure feels much cleaner.  Using the <code>doto</code> function allow you to chain function (Java method) calls together.</p> <p>Note  Start with the <code>import</code> function to add the necessary swing libraries.  Then create a button and add it to a panel, adding that panel to a frame.</p> <pre><code>(import '(javax.swing JFrame JPanel JButton))\n(def button (JButton. \"Click Me!\"))\n(def panel (doto (JPanel.)\n             (.add button)))\n(def frame (doto (JFrame. \"Hello Frame\")\n             (.setSize 200 200)\n             (.setContentPane panel)\n             (.setVisible true)))\n</code></pre> <p>Let\u2019s make our button show a message using an JOptionPane/showMessageDialog widget</p> <pre><code>(import 'javax.swing.JOptionPane)\n(defn say-hello []\n  (JOptionPane/showMessageDialog\n    nil \"Hello, World!\" \"Greeting\"\n    JOptionPane/INFORMATION_MESSAGE))\n</code></pre> <p>To connect this function to our button, write a class implementing the ActionListener interface.  Clojure\u2019s proxy feature is the easiest way to do this:</p> <pre><code>(import 'java.awt.event.ActionListener)\n(def act (proxy [ActionListener] []\n           (actionPerformed [event] (say-hello))))\n</code></pre> <p><code>act</code> is an instance of an anonymous class implementing the actionPerformed method, so attach this class as a listener the button</p> <pre><code>(.addActionListener button act)\n</code></pre> <p>Now evaluate the <code>say-hello</code> function to see the new button in action.</p> <pre><code>(say-hello)\n</code></pre> <p>Hint Seesaw is a really nice library for swing development.  Also talk a look at the Seesaw minesweeper series.</p>"},{"location":"reference/clojure-syntax/more-java-fun/#understanding-the-dot-special-form","title":"Understanding the dot special form","text":"<p>Fixme This section onwards needs reworking</p> <p>All of these examples (except java.lang.Math/PI) use macros which expand to use the dot special form. In general, you won't need to use the dot special form unless you want to write your own macros to interact with Java objects and classes. Nevertheless, here is each example followed by its macroexpansion:</p> <pre><code>(macroexpand-1 '(.toUpperCase \"By Bluebeard's bananas!\"))\n; =&gt; (. \"By Bluebeard's bananas!\" toUpperCase)\n\n(macroexpand-1 '(.indexOf \"Synergism of our bleeding edges\" \"y\"))\n; =&gt; (. \"Synergism of our bleeding edges\" indexOf \"y\")\n\n(macroexpand-1 '(Math/abs -3))\n; =&gt; (. Math abs -3)\n</code></pre> <p>You can think of the general form of the dot operator as:</p> <pre><code>(. object-expr-or-classname-symbol method-or-member-symbol optional-args*)\n</code></pre> <p>There are a few more details to the dot operator than that, and if you're interested in exploring it further you can look at clojure.org's documentation on Java interop.</p> <p>Input/output involves resources, be they files, sockets, buffers, or whatever. Java has separate classes for reading a resource's contents, writings its contents, and for interacting with the resource's properties.</p> <p>For example, the java.io.File class is used to interact with a file's properties. Among other things, you can use it to check whether a file exists, to get the file's read/write/execute permissions, and to get its filesystem path:</p> <pre><code>(let [file (java.io.File. \"/\")]\n  (println (.exists file))\n  (println (.canWrite file))\n  (println (.getPath file)))\n; =&gt; true\n; =&gt; false\n; =&gt; /\n</code></pre> <p>Noticeably missing from this list of capabilities are reading and writing. To read a file, you could use the java.io.BufferedReader class or perhaps java.io.FileReader. Likewise, you can use the java.io.BufferedWriter or java.io.FileWriter class for writing. There are other classes available for reading and writing as well, and which one you choose depends on your specific needs. Reader and Writer classes all have the same base set of methods for their interfaces; readers implement read, close, and more, while writers implement append, write, close, and flush. So, Java gives you a variety of tools for performing IO. A cynical person might say that Java gives you enough rope to hang yourself, and if you find such a person I hope you give them just enough arms to hug them.</p> <p>Either way, Clojure makes things easier for you. First, there's spit and slurp. Spit writes to a resource, and slurp reads from one. Here's an example of using them to write and read a file:</p> <pre><code>(spit \"/tmp/hercules-todo-list\"\n\"- wash hair\n - charm the multi-headed snake\")\n\n(slurp \"/tmp/hercules-todo-list\")\n\n; =&gt; \"- wash hair\n; =&gt;  - charm the multi-headed snake\"\n</code></pre> <p>You can also use these functions with objects representing resources other than files. The next example uses a StringWriter, which allows you to perform IO operations on a string:</p> <pre><code>(let [s (java.io.StringWriter.)]\n  (spit s \"- charm the multi-headed snake\")\n  (.toString s))\n; =&gt; \"- charm the multi-headed snake\"\n</code></pre> <p>Naturally, you can also read from a StringReader with slurp:</p> <pre><code>(let [s (java.io.StringReader. \"- charm the multi-headed snake\")]\n  (slurp s))\n; =&gt; \"- charm the multi-headed snake\"\n</code></pre> <p>Of course, you can also use the read and write methods for resources. It doesn't really make much of a difference which you use; spit and slurp are often convenient because they work with just a string representing a filesystem path or a URL.</p> <p>The with-open macro is another convenience: it implicitly closes a resource at the end of its body. There's also the reader function, a nice utility which, according to the clojure.java.io api docs, \"attempts to coerce its argument to an open java.io.Reader.\" This is convenient when you don't want to use slurp because you don't want to try to read a resource in its entirety, and you don't want to figure out which Java class you need to use. You could use it along with with-open and the line-seq function if you're trying to read a file one line at a time:</p> <pre><code>(with-open [todo-list-rdr (clojure.java.io/reader \"/tmp/hercules-todo-list\")]\n  (doseq [todo (line-seq todo-list-rdr)]\n    (println todo)))\n; =&gt; \"- wash hair\n; =&gt;  - charm the multi-headed snake\"\n</code></pre> <p>That should be enough for you to get started with IO in Clojure. If you're trying to do something more sophisticated, definitely take a look at the clojure.java.io docs, the java.nio.file package docs, or the java.io package docs. 5. Summary</p> <p>In this chapter, you learned what it means for Clojure to be hosted on the JVM. Clojure programs get compiled to Java bytecode and executed within a JVM process. Clojure programs also have access to Java libraries, and you can easily interact with them using Clojure's interop facilities. 6. Resources</p>"},{"location":"reference/clojure-syntax/more-java-fun/#from-httpclojureorgjava_interop","title":"From http://clojure.org/java_interop","text":"<pre><code>(.instanceMember instance args*)\n(.instanceMember Classname args*)\n(.-instanceField instance)\n\n(.toUpperCase \"fred\")\n-&gt; \"FRED\"\n(.getName String)\n-&gt; \"java.lang.String\"\n(.-x (java.awt.Point. 1 2))\n-&gt; 1\n(System/getProperty \"java.vm.version\")\n-&gt; \"1.6.0_07-b06-57\"\nMath/PI\n-&gt; 3.141592653589793\n</code></pre> <p>The preferred idiomatic forms for accessing field or method members are given above. The instance member form works for both fields and methods. The instanceField form is preferred for fields and required if both a field and a 0-argument method of the same name exist. They all expand into calls to the dot operator (described below) at macroexpansion time. The expansions are as follows:</p> <pre><code>(.instanceMember instance args*) ==&gt; (. instance instanceMember args*)\n(.instanceMember Classname args*) ==&gt;\n    (. (identity Classname) instanceMember args*)\n(.-instanceField instance) ==&gt; (. instance -instanceField)\n(Classname/staticMethod args*) ==&gt; (. Classname staticMethod args*)\nClassname/staticField ==&gt; (. Classname staticField)\n</code></pre> <p>The Dot special form</p> <pre><code>(. instance-expr member-symbol)\n(. Classname-symbol member-symbol)\n(. instance-expr -field-symbol)\n(. instance-expr (method-symbol args*)) or\n(. instance-expr method-symbol args*)\n(. Classname-symbol (method-symbol args*)) or\n(. Classname-symbol method-symbol args*)\n</code></pre> <p>Special form.</p> <p>The '.' special form is the basis for access to Java. It can be considered a member-access operator, and/or read as 'in the scope of'.</p> <p>If the first operand is a symbol that resolves to a class name, the access is considered to be to a static member of the named class. Note that nested classes are named EnclosingClass$NestedClass, per the JVM spec. Otherwise it is presumed to be an instance member and the first argument is evaluated to produce the target object.</p> <p>If the second operand is a symbol and no args are supplied it is taken to be a field access - the name of the field is the name of the symbol, and the value of the expression is the value of the field, unless there is a no argument public method of the same name, in which case it resolves to a call to the method. If the second operand is a symbol starting with -, the member-symbol will resolve only as field access (never as a 0-arity method) and should be preferred when that is the intent.</p> <p>If the second operand is a list, or args are supplied, it is taken to be a method call. The first element of the list must be a simple symbol, and the name of the method is the name of the symbol. The args, if any, are evaluated from left to right, and passed to the matching method, which is called, and its value returned. If the method has a void return type, the value of the expression will be nil. Note that placing the method name in a list with any args is optional in the canonic form, but can be useful to gather args in macros built upon the form.</p> <p>Note that boolean return values will be turned into Booleans, chars will become Characters, and numeric primitives will become Numbers unless they are immediately consumed by a method taking a primitive.</p> <p>The member access forms given at the top of this section are preferred for use in all cases other than in macros.</p> <pre><code>(.. instance-expr member+)\n(.. Classname-symbol member+)\nmember =&gt; fieldName-symbol or (instanceMethodName-symbol args*)\n</code></pre> <p>Macro. Expands into a member access (.) of the first member on the first argument, followed by the next member on the result, etc. For instance:</p> <pre><code>(.. System (getProperties) (get \"os.name\"))\n</code></pre> <p>expands to:</p> <pre><code>(. (. System (getProperties)) (get \"os.name\"))\n</code></pre> <p>but is easier to write, read, and understand. See also the -&gt; macro which can be used similarly:</p> <pre><code>(-&gt; (System/getProperties) (.get \"os.name\"))\n</code></pre> <p>(doto instance-expr (instanceMethodName-symbol args)) Macro. Evaluates instance-expr then calls all of the methods/functions with the supplied arguments in succession on the resulting object, returning it.</p> <pre><code>(doto (new java.util.HashMap) (.put \"a\" 1) (.put \"b\" 2))\n-&gt; {a=1, b=2}\n</code></pre> <p>Note the above applies to the latest Clojure SVN revision. If you are using the 20080916 release only method calls are allowed, and the syntax is:</p> <pre><code>(doto (new java.util.HashMap) (put \"a\" 1) (put \"b\" 2))\n-&gt; {a=1, b=2}\n</code></pre> <p>(Classname. args) (new Classname args)</p> <p>Special form. The args, if any, are evaluated from left to right, and passed to the constructor of the class named by Classname. The constructed object is returned.</p> <p>Alternative Macro Syntax</p> <p>As shown, in addition to the canonic special form new, Clojure supports special macroexpansion of symbols containing '.':</p> <pre><code>(new Classname args*)\n</code></pre> <p>can be written</p> <pre><code>(Classname. args*)\n;; note trailing dot\n</code></pre> <p>the latter expanding into the former at macro expansion time.</p> <p>(instance? Class expr) Evaluates expr and tests if it is an instance of the class. Returns true or false</p> <p>(set! (. instance-expr instanceFieldName-symbol) expr) (set! (. Classname-symbol staticFieldName-symbol) expr) Assignment special form. When the first operand is a field member access form, the assignment is to the corresponding field. If it is an instance field, the instance expr will be evaluated, then the expr.</p> <p>In all cases the value of expr is returned.</p> <p>Note - you cannot assign to function params or local bindings. Only Java fields, Vars, Refs and Agents are mutable in Clojure.</p> <p>(memfn method-name arg-names*) Macro. Expands into code that creates a fn that expects to be passed an object and any args and calls the named instance method on the object passing the args. Use when you want to treat a Java method as a first-class fn.</p> <p>(map (memfn charAt i) [\"fred\" \"ethel\" \"lucy\"] [1 2 3]) -&gt; (\\r \\h \\y)</p> <p>Note it almost always preferable to do this directly now, with syntax like:</p> <p>(map #(.charAt %1 %2) [\"fred\" \"ethel\" \"lucy\"] [1 2 3]) -&gt; (\\r \\h \\y)</p> <p>(bean obj) Takes a Java object and returns a read-only implementation of the map abstraction based upon its JavaBean properties.</p> <p>(bean [[http://java.awt.Color/black|java.awt.Color/black]]) -&gt; {:RGB -16777216, :alpha 255, :transparency 1,     :class class java.awt.Color, :green 0, :blue 0,     :colorSpace java.awt.color.ICC_ColorSpace@c94b51, :red 0}</p> <p>Support for Java in Clojure Library Functions</p> <p>Many of the Clojure library functions have defined semantics for objects of Java types. contains? and get work on Java Maps, arrays, Strings, the latter two with integer keys. count works on Java Strings, Collections and arrays. nth works on Java Strings, Lists and arrays. seq works on Java reference arrays, Iterables and Strings. Since much of the rest of the library is built upon these functions, there is great support for using Java objects in Clojure algorithms.</p> <p>Implementing Interfaces and Extending Classes</p> <p>Clojure supports the dynamic creation of objects that implement one or more interfaces and/or extend a class with the proxy macro. The resulting objects are of an anonymous class. You can also generate statically-named classes and .class files with gen-class. As of Clojure 1.2, reify is also available for implementing interfaces.</p> <p>( proxy [class-and-interfaces] [args] fs+) class-and-interfaces - a vector of class names args - a (possibly empty) vector of arguments to the superclass constructor. f =&gt; (name [params] body) or (name ([params] body) ([params+] body) ...)</p> <p>Macro</p> <p>Expands to code which creates a instance of a proxy class that implements the named class/interface(s) by calling the supplied fns.</p> <p>A single class, if provided, must be first. If not provided it defaults to Object.</p> <p>The interfaces names must be valid interface types. If a method fn is not provided for a class method, the superclass method will be called.</p> <p>If a method fn is not provided for an interface method, an UnsupportedOperationException will be thrown should it be called.</p> <p>Method fns are closures and can capture the environment in which proxy is called. Each method fn takes an additional implicit first argument, which is bound to this.</p> <p>Note that while method fns can be provided to override protected methods, they have no other access to protected members, nor to super, as these capabilities cannot be a proxy.</p> <p>Arrays</p> <p>Clojure supports the creation, reading and modification of Java arrays. It is recommended that you limit use of arrays to interop with Java libraries that require them as arguments or use them as return values.</p> <p>Note that many other Clojure functions work with arrays such as via the seq library. The functions listed here exist for initial creation of arrays, or to support mutation or higher performance operations on arrays.</p> <p>Create array from existing collection: aclone amap to-array to-array-2d into-array Multi-dimensional array support: aget aset to-array-2d make-array Type-specific array constructors: boolean-array byte-array char-array double-array float-array int-array long-array object-array short-array Primitive array casts: booleans bytes chars doubles floats ints longs shorts Mutate an array: aset Process an existing array: aget alength amap areduce</p> <p>Type Hints</p> <p>Clojure supports the use of type hints to assist the compiler in avoiding reflection in performance-critical areas of code. Normally, one should avoid the use of type hints until there is a known performance bottleneck. Type hints are metadata tags placed on symbols or expressions that are consumed by the compiler. They can be placed on function parameters, let-bound names, var names (when defined), and expressions:</p> <p>(defn len [x]   (.length x))</p> <p>(defn len2 [^String x]   (.length x))</p> <p>user=&gt; (time (reduce + (map len (repeat 1000000 \"asdf\")))) \"Elapsed time: 3007.198 msecs\" 4000000 user=&gt; (time (reduce + (map len2 (repeat 1000000 \"asdf\")))) \"Elapsed time: 308.045 msecs\" 4000000</p> <p>Once a type hint has been placed on an identifier or expression, the compiler will try to resolve any calls to methods thereupon at compile time. In addition, the compiler will track the use of any return values and infer types for their use and so on, so very few hints are needed to get a fully compile-time resolved series of calls. Note that type hints are not needed for static members (or their return values!) as the compiler always has the type for statics.</p> <p>There is a warn-on-reflection flag (defaults to false) which will cause the compiler to warn you when it can't resolve to a direct call:</p> <p>(set! warn-on-reflection true) -&gt; true</p> <p>(defn foo [s] (.charAt s 1)) -&gt; Reflection warning, line: 2 - call to charAt can't be resolved. -&gt; #user/foo</p> <p>(defn foo [^String s] (.charAt s 1)) -&gt; #user/foo</p> <p>For function return values, the type hint can be placed before the arguments vector:</p> <p>(defn hinted   (^String [])   (^Integer [a])   (^java.util.List [a &amp; args]))</p> <p>-&gt; #user/hinted</p> <p>Aliases</p> <p>Clojure provides aliases for primitive Java types and arrays which do not have typical representations as Java class names. For example, long arrays (long-array []) have a type of \"[J\".</p> <pre><code>int - A primitive int\nints - An int array\nlong - A primitive long\nlongs - A long array\nfloat - A primitive float\nfloats - A float array\ndouble - A primitive double\ndoubles - A double array\nvoid - A void return\nshort - A primitive short\nshorts - A short array\nboolean - A primitive boolean\nbooleans - A boolean array\nbyte - A primitive byte\nbytes - A byte array\nchar - A primitive character\nchars - A character array\n</code></pre> <p>Support for Java Primitives</p> <p>Clojure has support for high-performance manipulation of, and arithmetic involving, Java primitive types in local contexts. All Java primitive types are supported: int, float, long, double, boolean, char, short, and byte.</p> <pre><code>let/loop-bound locals can be of primitive types, having the inferred, possibly primitive type of their init-form.\nrecur forms that rebind primitive locals do so without boxing, and do type-checking for same primitive type.\nArithmetic (+,-,*,/,inc,dec,&lt;,&lt;=,&gt;,&gt;= etc) is overloaded for primitive types where semantics are same.\naget/aset are overloaded for arrays of primitives\naclone, alength functions for arrays of primitives\nconstructor functions for primitive arrays: float-array, int-array, etc.\nType hints for primitive arrays - ^ints, ^floats, etc.\nCoercion ops int, float, etc. produce primitives when consumer can take primitive\nThe num coercion function boxes primitives to force generic arithmetic\nArray cast functions ints longs, etc. which produce int[], long[], etc.\nA set of \"unchecked\" operations for utmost performing, but potentially unsafe, integer (int/long) ops: unchecked-multiply unchecked-dec unchecked-inc unchecked-negate unchecked-add unchecked-subtract unchecked-remainder unchecked-divide\nA dynamic var to automatically swap safe operations with unchecked operations: *unchecked-math*\namap and areduce macros for functionally (i.e. non-destructively) processing one or more arrays in order to produce a new array or aggregate value respectively.\n</code></pre> <p>Rather than write this Java:</p> <p>static public float asum(float[] xs){   float ret = 0;   for(int i = 0; i &lt; xs.length; i++)     ret += xs[i];   return ret; }</p> <p>you can write this Clojure:</p> <p>(defn asum [^floats xs]   (areduce xs i ret (float 0)     (+ ret (aget xs i))))</p> <p>and the resulting code is exactly the same speed (when run with java -server).</p> <p>The best aspect of this is that you need not do anything special in your initial coding. Quite often these optimizations are unneeded. Should a bit of code be a bottleneck, you can speed it up with minor adornment:</p> <p>(defn foo [n]   (loop [i 0]     (if (&lt; i n)       (recur (inc i))       i)))</p> <p>(time (foo 100000)) \"Elapsed time: 0.391 msecs\" 100000</p> <p>(defn foo2 [n]   (let [n (int n)]     (loop [i (int 0)]       (if (&lt; i n)         (recur (inc i))         i))))</p> <p>(time (foo2 100000)) \"Elapsed time: 0.084 msecs\" 100000</p> <p>Coercions At times it is necessary to have a value of a particular primitive type. These coercion functions yield a value of the indicated type as long as such a coercion is possible: bigdec bigint boolean byte char double float int long num short</p> <p>Some optimization tips</p> <pre><code>All arguments are passed to Clojure fns as objects, so there's no point to putting non-array primitive type hints on fn args. Instead, use the let technique shown to place args in primitive locals if they need to participate in primitive arithmetic in the body.\n(let [foo (int bar)] ...) is the correct way to get a primitive local. Do not use ^Integer etc.\nDon't rush to unchecked math unless you want truncating operations. HotSpot does a good job at optimizing the overflow check, which will yield an exception instead of silent truncation. On a typical example, that has about a 5% difference in speed - well worth it. Also, people reading your code don't know if you are using unchecked for truncation or performance - best to reserve it for the former and comment if the latter.\nThere's usually no point in trying to optimize an outer loop, in fact it can hurt you as you'll be representing things as primitives which just have to be re-boxed in order to become args to the inner call. The only exception is reflection warnings - you must get rid of them in any code that gets called frequently.\nAlmost every time someone presents something they are trying to optimize with hints, the faster version has far fewer hints than the original. If a hint doesn't improve things in the end - take it out.\nMany people seem to presume only the unchecked- ops do primitive arithmetic - not so. When the args are primitive locals, regular + and * etc do primitive math with an overflow check - fast and safe.\nSo, the simplest route to fast math is to leave the operators alone and just make sure the source literals and locals are primitive. Arithmetic on primitives yields primitives. If you've got a loop (which you probably do if you need to optimize) make sure the loop locals are primitives first - then if you accidentally are producing a boxed intermediate result you'll get an error on recur. Don't solve that error by coercing your intermediate result, instead, figure out what argument or local is not primitive.\n</code></pre> <p>Simple XML Support Included with the distribution is simple XML support, found in the src/xml.clj file. All names from this file are in the xml namespace.</p> <p>(parse source) Parses and loads the source, which can be a File, InputStream or String naming a URI. Returns a tree of the xml/element struct-map, which has the keys :tag, :attrs, and :content. and accessor fns tag, attrs, and content.</p> <p>(xml/parse \"/Users/rich/dev/clojure/build.xml\") -&gt; {:tag :project, :attrs {:name \"clojure\", :default \"jar\"}, :content [{:tag :description, ...</p> <p>Calling Clojure From Java The clojure.java.api package provides a minimal interface to bootstrap Clojure access from other JVM languages. It does this by providing:</p> <ol> <li>The ability to use Clojure's namespaces to locate an arbitrary var, returning the var's clojure.lang.IFn interface.</li> <li>A convenience method read for reading data using Clojure's edn reader</li> </ol> <p>IFns provide complete access to Clojure's APIs. You can also access any other library written in Clojure, after adding either its source or compiled form to the classpath.</p> <p>The public Java API for Clojure consists of the following classes and interfaces:</p> <pre><code>clojure.java.api.Clojure\nclojure.lang.IFn\n</code></pre> <p>All other Java classes should be treated as implementation details, and applications should avoid relying on them.</p> <p>To lookup and call a Clojure function:</p> <p>IFn plus = Clojure.var(\"clojure.core\", \"+\"); plus.invoke(1, 2);</p> <p>Functions in clojure.core are automatically loaded. Other namespaces can be loaded via require:</p> <p>IFn require = Clojure.var(\"clojure.core\", \"require\"); require.invoke(Clojure.read(\"clojure.set\"));</p> <p>IFns can be passed to higher order functions, e.g. the example below passes plus to read:</p> <p>IFn map = Clojure.var(\"clojure.core\", \"map\"); IFn inc = Clojure.var(\"clojure.core\", \"inc\"); map.invoke(inc, Clojure.read(\"[1 2 3]\"));</p> <p>Most IFns in Clojure refer to functions. A few, however, refer to non-function data values. To access these, use deref instead of fn:</p> <p>IFn printLength = Clojure.var(\"clojure.core\", \"print-length\"); IFn deref = Clojure.var(\"clojure.core\", \"deref\"); deref.invoke(printLength);</p>"},{"location":"reference/clojure-syntax/naming/","title":"Naming","text":""},{"location":"reference/clojure-syntax/naming/#naming-when-requiring-other-namespaces","title":"Naming when requiring other namespaces","text":"<p><code>(require [cheshire.core :refer :all])</code> is an example of self-inflicted errors, as this library included a <code>contains?</code> function that will over-write the <code>clojure.core/contains?</code> function when using <code>:refer :all</code> or the <code>(use )</code> expression.</p> <p>This situation is one example of why <code>:refer :all</code> and <code>use</code> are not recommended and can cause lots of debugging headaches.</p> <p>If a namespace is predominantly about using a specific library, then refer specific functions as they are used within the current namespace</p> <pre><code>(ns current.namespace\n(:require\n  [cheshire.core :refer [function-name another-function etc]))\n</code></pre> <p>A classic example is a test namespace that uses clojure core (ns practicalli.random-function-test   (:require [clojure.test :refer [deftest is testing]]             [practicalli.random-function :as sut])) Otherwise use a meaningful alias, ideally referring to what that library is doing (which makes it easer to swap out with a different library later on if required).  As Cheshire is a JSON related library, then (ns my.ns   (:require [cheshire.core :as json])) This gives a context to all the functions called from that library and makes code easier for humans to understand.</p>"},{"location":"reference/clojure-syntax/naming/#hintclj-kondo-lint-tool-shows-unused-functions","title":"Hint::clj-kondo lint tool shows unused functions","text":"<p>Using clj-kondo</p>"},{"location":"reference/clojure-syntax/numbers-maths/","title":"Maths","text":"<p>Fixme Split this into sections ?</p> <p>Writing some simple mathematics helps you get used to the form of Clojure.  Unlike other languages, Clojure does not have operators for mathematics.  Instead <code>+ - * /</code> are all functions in their own right.</p> <p>As Clojure uses pre-fix notation then mathematical expressions are always unambiguous.  There is no need for an operator precedence table in Clojure.</p> <p>Note Write some simple math to help you get used to the form of Clojure</p> <pre><code>(+ 1 2 3 4 5 6 7)\n(- 2 1)\n(* 3 7)\n(/ 12 4)\n(/ 500 20)\n(+ 1 1 2489 459 2.)\n(+ 1 2 (* 3 4) (- 5 6 -7))\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/numbers-maths/#variable-numbers-of-arguments","title":"Variable numbers of arguments","text":"<p>Mathematic functions show the flexibility of Clojure, as they take a variable number of arguments (variadic functions).  Its common for Clojure functions to have zero, one or many arguments (many arguments typically represented as a built-in data structure (map, vector, set or list)</p> <p>Note Write some more maths to show the variadic nature of mathematic (and manu other) functions</p> <pre><code>(+)\n(*)\n(* 2)\n(+ 4)\n\n(+ 1 2 3)\n(&lt; 1 2 3)\n(&lt; 1 3 8 4)\n</code></pre> <p></p> <p>Note Explore some number related functions</p> <pre><code>(rem 22 7)\n(mod 20 12)\n(quot 13 4)\n\n(inc 3)\n(dec 4)\n\n(min 1 2 3 5 8 13)\n(max 1 2 3 5 8 13)\n\n(repeat 4 9)\n\n(range 10)\n(range 18 66)\n(range 2 99 2)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#equality","title":"Equality","text":"<p>Equality is represented by the <code>=</code> function.  Yes, <code>=</code> is a proper function too, not just an operator as with other languages.</p> <p>Note Explore what equality means in Clojure.  Equality is very useful when your data structures are immutable</p> <pre><code>(= 1 1)\n(= 2 1)\n\n(identical? \"foo\" \"bar\")\n(identical? \"foo\" \"foo\")\n(= \"foo\" \"bar\")\n(= \"foo\" \"foo\")\n\n(identical? :foo :bar)\n(identical? :foo :foo)\n\n(true)\n(false)\n(not true)\n(true? (= 1 1))\n(false (= 1 -1))\n</code></pre> <p>Equality is very efficient when your data structures are immutable.  For example if you have very large data sets, you can simply compare a hash value to see if those data structures are the same.</p> <p>Of course you also have the <code>not</code> function for reversing logic too</p> <pre><code>(not true)\n\n=&gt; false\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#boolean-true-and-false","title":"Boolean - True and False","text":"<p>;; some truthiness with math functions for you to try</p> <pre><code>(+)\n(class (+))\n(*)\n(true? +)\n(false? +)\n(true? *)\n(false? *)\n(true? 1)\n(true? -1)\n(true? true)\n(- 2)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#boolean-predicates","title":"Boolean &amp; Predicates","text":"<p>Predicates are functions that take a value and return a boolean result (true | false)</p> <pre><code>(true? true)\n(true? (not true))\n(true? false)\n(true? (not false))\n(true? nil)\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#types","title":"Types","text":"<p>Clojure uses Java's object types for booleans, strings and numbers.  Use the <code>class</code> function to inspect them.</p> <pre><code>(class 1)\n; Integer literals are java.lang.Long by default\n(class 1.1)    ; Float literals are java.lang.Double\n\n(class \"\")\n; Strings always double-quoted, and are java.lang.String\n\n(class false)  ; Booleans are java.lang.Boolean\n(class nil)    ; The \"null\" value is called nil\n\n(class (list 1 2 3 4))\n\n\n(class true)\n(class ())\n(class (list 1 2 34 5))\n(class (str 2 3 4 5))\n(class (+ 22/7))\n(class 5)\n(class \"fish\")\n(type [1 2 3])\n(type {:a 1 :b 2})\n\n(type (take 3 (range 10)))\n</code></pre>"},{"location":"reference/clojure-syntax/numbers-maths/#ratios","title":"Ratios","text":"<p>To help maintain the precision of numbers, Clojure has a type called Ratio.  So when you are dividing numbers you can keep the as a fraction using whole numbers, rather than constrain the result to a approximate</p> <pre><code>(/ 2)\n</code></pre> <p>A classic example is dividing 22 by 7 which is approximately the value of Pi</p> <pre><code>(/ 22 7)\n\n(class (/ 22 7))\n</code></pre> <p>If you want to force Clojure to evaluate this then you can specify one of the numbers with a decimal point</p> <pre><code>(class (/ 22 7.0))\n</code></pre>"},{"location":"reference/clojure-syntax/parenthesis/","title":"Parenthesis - defining the structure of Clojure code","text":"<p>Clojure uses parenthesis, round brackets <code>()</code>, as a simple way to define the structure of the code and provide clear and unambiguous scope.  This structure is the syntax of symbolic expressions.</p> <p></p> <p>Parenthesis, or parens for short, are used to define and call functions in our code, include libraries and in fact any behavior we wish to express.</p> <p>Clojure includes 3 other bracket types to specifically identify data: <code>'()</code> quoted lists and sequences, <code>[]</code> for vectors (arrays) and argument lists, <code>{}</code> for hash-maps and <code>#{}</code> for sets of data.</p> <p>No other terminators or precedence rules are required to understand how to read and write Clojure.</p>"},{"location":"reference/clojure-syntax/parenthesis/#the-parenthesis-hangup","title":"The Parenthesis hangup","text":"<p>Some raise the concern that there are \"too many brackets\" in Clojure.</p> <p>Clojure doesn't require any additional parens compared to other languages, it simply moves the open parens to the start of the expression giving a clearly defined structure to the code</p> <p>With support for higher order functions, functional composition and threading macros, Clojure code typically uses fewer parens than other languages especially as the scope of the problem space grows.</p> <p>All languages use parens to wrap a part of an expression, requiring additional syntax to identify the boundaries of each expression so it can be parsed by humans and computers alike.  Clojure uses a single way to express everything, homoiconicity, where as most other languages require additional syntax for different parts of the code.</p> <p>Using parens, Clojure has a well defined structure that provides a clearly defined scope to every part of the code.  There is no requirement to remember a long list of ad-hoc precedence rules, e.g. JavaScript operator precedence.</p> <p>This structure of Clojure code is simple to parse for both humans and computers.  it is simple to navigate, simple to avoid breaking the syntax of the language and simple to provide tooling that keeps the syntax of the code correct.</p> <p>After realising the simplicity that parens bring, you have to wonder why other (non-lisp) languages made their syntax more complex.</p>"},{"location":"reference/clojure-syntax/parenthesis/#working-with-parens","title":"Working with Parens","text":"<p>Clojure aware editors all support structured editing to manage parens and ensure they remain balanced (same number of open and close parens).</p> <p>A developer only needs to type the open paren and the editor will automatically add the closing paren.</p> <p>Parens cannot be deleted unless their content is empty.</p> <p>Code can be pulled into parens (slurp) or pushed out of parens (barf).  Code can be split, joined, wrapped, unwrapped, transposed, convoluted and raised, all without breaking the structure.</p> <ul> <li>Smartparens for Structural editing - a modern update of ParEdit</li> <li>The animated guide to ParEdit</li> </ul>"},{"location":"reference/clojure-syntax/parenthesis/#homoiconicity-and-macros","title":"Homoiconicity and Macros","text":"<p>Clojure is a dialect of LISP and naturally was designed to be a homoiconic language. This means the syntax for behavior and data is the same.  This greatly simplifies the syntax of Clojure and all LISP style languages.</p> <p>The Clojure Reader is a parser that reads in data structures as expression, rather than parsing of text required by other languages. The result of parsing is a collection of data structures that can be traversed (asymmetric syntax tree - AST).  Compared to most languages the compiler does very little and you can consider Clojure really does not have a syntax.</p> <p>Code is written as data structures that are accessible to the other parts of the code, providing a way to write code that manipulate those data structures and generate new code. In Clojure this type of code is called a macro, a piece of code that writes new code.</p> <p></p> <p>None of this would work as simply as it does without using parens and the symbolic expression syntax.</p> <ul> <li>Inspired by Beating the Averages by Paul Graham</li> </ul>"},{"location":"reference/clojure-syntax/parenthesis/#example-function-invocation","title":"Example: Function invocation","text":"<p>The choice was made early in the design of Lisp that lists would be used for function invocation in the form:</p> <pre><code>(function arg1 arg2 arg3)\n;; =&gt; value returned\n</code></pre> <p>The advantages of this design are:</p> <ul> <li>a function call is just one expression, called a \"form\"</li> <li>function calls can be constructed  (cons function-symbol list-of-args)</li> <li>functions can be arguments to other functions (higher order functions)</li> <li>simple syntax to parse - everything between two parentheses is a self-contained expression.</li> <li>fewer parens due to high order functions, composition and threading macros</li> </ul> <p>The function name could have been put outside the parentheses:</p> <pre><code>function (arg1 arg2 arg3) =&gt; some result\n</code></pre> <p>This design has many disadvantages:</p> <ul> <li>a function call is no longer a single form and have to pass the function name and the argument list.</li> <li>syntax is complex and requires additional syntax rules to define a function call</li> <li>code generation is very complex</li> <li>same number of parens as Clojure or possibly more (no direct support for higher order functions)</li> </ul>"},{"location":"reference/clojure-syntax/private-functions/","title":"Private functions","text":"<p>Fixme work in progress</p>"},{"location":"reference/clojure-syntax/quick-look-at-types/","title":"A quick look at types","text":"<p>As we mentioned before, underneath Clojure lurks Java byte code so there are going to be types in Clojure.  However, Clojure being a dynamic language, most of the time you can just let Clojure manage the types for you.</p> <p>Hint When you run Clojure on a different host platform, eg. .Net or Javascript (via Clojurescript), Clojure will use the types of that host platform.</p> <p>Should you want to know the type of something you are working on, you can use two functions, <code>type</code> and <code>class</code>.</p> <p>Note Discover the class or type of some common Clojure code</p> <pre><code>(class 1)\n(class 1.1)\n(class \"\")\n(class true)\n(class false)\n(class nil)\n\n(class ())\n(class (list 1 2 3 4))\n(class (str 2 3 4 5))\n(class (+ 22/7))\n\n(type [1 2 3])\n(type {:a 1 :b 2})\n(type (take 3 (range 10)))\n</code></pre> <p></p> <p>Hint If you cant live without static type checking, look at core.typed, a type system for Clojure all in one library</p>"},{"location":"reference/clojure-syntax/ratios/","title":"Ratios","text":"<p>In mathematics you need to ensure that you manage precision of your calculations when you are dividing numbers.  Once you create a decimal number then everything it touches had a greater potential to becoming a decimal.</p> <p>Note Calculate a rough approximation to Pi by dividing 22 by 7</p> <pre><code>(/ 22 7)\n(class (/ 22 7))\n(/ (* 22/7 3) 3)\n</code></pre> <p></p> <p>If the result of an integer calculation would be a decimal number, then Clojure holds the value as a Ratio.  This is one example of lazy evaluation.  Rather than calculate the decimal value at some particular precision (number of decimal points).  Clojure is saving the calculation until its needed, at which time the specific precision required should be known.</p> <p>Note Explore the ratio type further and see how to get a decimal value as the result</p> <pre><code>(/ 14 4)\n(/ 16 12)\n(/ 2)\n(/ 22 7.0)\n(type (/ 22 7.0))\n(float (/ 22 7))\n(double (/ 22 7))\n</code></pre> <p></p> <p>When one or more of the numbers in the division is a decimal, then Clojure will return a decimal value.  Or you can coerce a value to a specific decimal type, eg. float or double.</p>"},{"location":"reference/clojure-syntax/strings/","title":"Strings","text":"<p>Strings in Clojure are actually Java Strings.</p> <p>Hint  Why do you think this design decision was taken for Clojure?</p> <p>If you think about the state property of String objects, then you realise that String Objects are immutable and cannot be changed.  As this is the default approach for other data structures and values in Clojure it makes sense to use Java Strings instead of writing a Clojure implementation.</p> <p>As Clojure strings are Java strings, then you can use all the same functions you can in Java.</p> <p>Note Use the Java function <code>println</code> to output a string</p> <pre><code>(println \"Hello, whats different with me?  What value do I return\")\n</code></pre> <p></p> <p>Something different happens when you evaluate this expression.  The actual value returned is <code>nil</code>, not the string.  You see the string because println is writing to the console (i.e the REPL).</p> <p>Hint Avoid code that creates side-effects where possible to keep your software less complex to understand.</p> <p>You may be used to using println statements to help you debug your code, however, with the fast feedback you get from developing in the REPL then there is usually no need for them.</p>"},{"location":"reference/clojure-syntax/strings/#strings-the-clojure-way","title":"Strings the Clojure way","text":"<p>Its more common to use the <code>str</code> function when working with strings, as this function returns the string as its. value when evaluated.</p> <p>(str \"Hello, I am returned as a value of this expression\")</p> <p>Note Join strings together with the function str</p> <pre><code>(str \"I\" \"like\" \"to\" \"be\" \"close\" \"together\"\n(str \"Hello\" \", \" \"Devoxx UK\")\n(str \"Hello \"  \"developers\" \", \" \"welcome\" \" \" \"to\" \" \" \"HackTheTower UK\")\n</code></pre> <p>You can see that there are no side-effects when using <code>str</code> and the string is returned as the value of the function call.</p>"},{"location":"reference/clojure-syntax/strings/#using-interpose-with-strings","title":"Using Interpose with Strings","text":"<p>Its easy to join strings together with the <code>str</code> function, however <code>str</code> leaves no spaces between words.</p>"},{"location":"reference/clojure-syntax/strings/#using-regex","title":"Using Regex","text":""},{"location":"reference/clojure-syntax/strings/#java-interop-for-strings","title":"Java Interop for Strings","text":"<p>Note Change the case of strings and other common actions using the String object methods, in the form <code>(.methodName object)</code></p> <pre><code>(.toUpperCase \"show me the money\")\n\n(.getName String)\n\n(.indexOf \"Where is the $ in this string\" \"$\")\n</code></pre> <p>Hint Look at the API docs for java.lang.String for other methods you can call.</p>"},{"location":"reference/clojure-syntax/syntax/","title":"Clojure syntax","text":"<p>Clojure is perceived as having an abundance of <code>()</code>, the symbols that represent a list.</p> <p>As Clojure is a LISP (List Processing) language then everything is written in the form of a list.  This makes Clojure very powerful and also easier to read.</p> <p>Using a list structure also demonstrates the data-centric nature of Clojure.  Every item in the list has a value, with the first item evaluated by a function call.</p>"},{"location":"reference/clojure-syntax/syntax/#hintparens-everywhere","title":"Hint::Parens everywhere","text":"<p>The seemingly abundance of <code>()</code> can be confusing until its realized there are fewer \"special characters\" in Clojure than other languages.  Clojure aware editors support matching parens, adding a closed paren when typing an open paren, ensuring it is easy to write correctly formed Clojure.</p> <p>Syntax differences are a trivial reason to avoid trying Clojure.  Syntax aware editors significantly reduce typing by automatically closing parenthesis and eliminating errors due to missing delimiters (ie. no more errors due to missing ; in C-based languages)</p>"},{"location":"reference/clojure-syntax/syntax/#prefix-notation","title":"Prefix notation","text":"<p>Instead of having a mix of notations like in many other languages, Clojure uses pre-fix notation entirely.</p> <p>In Clojure operators are applied uniformly and there is no room for ambiguity:</p> <pre><code>    (+ 1 2 3 5 8 13 21)\n    (+ 1 2 (- 4 1) 5 (* 2 4) 13 (/ 42 2))\n    (str \"Clojure\" \" uses \" \"prefix notation\")\n</code></pre> <p>In Java and other C-based languages you have to explicitly add operators everywhere and there can be a mixture of notations</p> <pre><code>    (1 + 2 + 3 + 5 + 8 + 13 + 21);\n    (1 + 2 + (- 4 1) + 5 + (* 2 4) + 13 + (/ 42 2));\n    StringBuffer description = new StringBuffer(\"C-based languages\" + \" mix \" + \"notation\");\n    x+=1;\n    x++;\n    x--;\n    x+=y;\n    x-=y;\n    x*=y;\n    x/=y;\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#references","title":"References","text":"<ul> <li>Clojure Style Guide</li> </ul>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/","title":"Threading Syntax Sugar","text":"<p>The previous code is written in classic Lisp style.  When you come to read Lisp, you start from the inside out.  In this case you start with <code>(slurp ...)</code> and what it returns is used as the argument to <code>(read-string ...)</code> and so on...</p> <p>In our minds we probably constructed the following basic algorithm:</p> <ul> <li>Get the contents of the project.clj file using <code>slurp</code></li> <li>Read the text of that file using read-string</li> <li>Select just the third string using nth 2 (using an index starting at 0)</li> </ul> <p>Can we rewrite our Clojure code to fit the way we think?</p>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#thread-first-macro","title":"Thread first macro","text":"<p>Using the thread-first macro -&gt; we can chain Clojure functions together with a terser syntax, passing the result of the first evaluation as the first argument to the next function and so on.  Using this style, we can write code that matches the algorithm in our head.</p> <p>To make this really simple lets create a contrived example of the threading macro.  Here we use the <code>str</code> function to join strings together.  Each individual <code>str</code> function joins its own strings together, passing the resulting string as the first argument to the next function.</p> <pre><code>(-&gt;\n (str \"This\" \" \" \"is\" \" \")\n (str \"the\" \" \" \"threading\" \" \" \"macro\")\n (str \"in\" \" \" \"action.\"))\n\n;; =&gt; \"This is the threading macro in action\"\n</code></pre>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#thread-last-macro","title":"Thread-last macro","text":"<p>Using the thread-last macro, -&gt;&gt;, the result of a function is passed as the last argument of the next function call.  So in another simple series of str function calls, our text comes out backwards.</p> <pre><code>(-&gt;&gt;\n (str \" This\")\n (str \" is\")\n (str \" backwards\"))\n\n;; =&gt; backwards is This\"\n</code></pre>"},{"location":"reference/clojure-syntax/threading-syntactic-sugar/#_1","title":"Threading Syntax Sugar","text":"<p>Note Refactor the Clojure code using the thread-first macro</p> <pre><code>(-&gt;\n \"./project.clj\"\n slurp\n read-string\n (nth 2))\n</code></pre> <p>Hint The \"project.clj\" is a string, so when you evaluate it as an expression, it simply returns the same string.  That string is then passed as an argument to any following functions.</p> <p>Using the threading macro, the result of every function is passed onto the next function in the list.  This can be seen very clearly using ,,, to denote where the value is passed to the next function</p> <pre><code>(-&gt;\n \"project.clj\"\n slurp ,,,\n read-string ,,,\n (nth ,,, 2))\n</code></pre> <p>Hint Commas in clojure are treated as whitespace, they are simply ignored when it comes to evaluating code.  Typically commas are rarely used and only to help human readability of the code</p> <p>Note Create a new map that contains the project configuration for the current project</p> <pre><code>(-&gt;&gt; \"project.clj\"\n     slurp\n     read-string\n     (drop 2)\n     (cons :version)\n     (apply hash-map)\n     (def project-configs))\n\n;; Evaluate the new map defined as project\nproject\n</code></pre> <p>We pull out the map of project information using <code>slurp</code>, tidy the text up using <code>read-string</code> and drop the first two elements (defproject playground).  This returns a list that we want to turn into a map, but first we need to add a key to the version number.  Using the <code>cons</code> function we can add an element to the start of the list, in this case the <code>:version</code> keyword</p> <p>Now we can successfully convert the list that is returned into a map, with balanced key-value pairs.  Then we simply create a name for this new map, <code>project-configs</code>, so we can refer to it elsewhere in the code.</p> <p>Hint The <code>slurp</code> function holds the contents of the whole file in memory, so it may not be appropriate for very large files.  If you are dealing with a large file, consider wrapping slurp in a lazy evaluation or use Java IO (eg. <code>java.io.BufferedReader</code>, <code>java.io.FileReader.</code>).  See the Clojure I/O cookbook and The Ins &amp; Outs of Clojure for examples.</p>"},{"location":"reference/clojure-syntax/whats-my-environment/","title":"Whats my environment","text":"<p>Clojure has symbols (names that point to values).  Some of these symbols are built into the language and their names start (and usually end with) the <code>*</code> character.</p> <p>When symbols are evaluated they return the value that they point to.</p> <p>Note Check the version of Clojure running in your REPL.</p> <p>Enter the following code into the Clojure REPL:</p> <pre><code>*clojure-version*\n</code></pre> <p></p> <p>The full clojure version can be used to check you are running a particular version, major or minor of Clojure core.  This information is represented as a map containing <code>:major</code>, <code>:minor</code>, <code>:incremental</code> and <code>:qualifier</code> keys.    Feature releases may increment :minor and/or :major, bugfix releases will increment :incremental.  Possible values of :qualifier include \"GA\", \"SNAPSHOT\", \"RC-x\" \"BETA-x\"</p> <p>Hint A map in Clojure is a built in data structure represented by <code>{ }</code>. A map is a key-value pair and there must be a value for every key for the map to be valid.  Keys are often defined using <code>:keyword</code>, a self-referential pointer that can be used to look up values in a map or other data structures.</p>"},{"location":"reference/clojure-syntax/whats-my-environment/#viewing-the-class-path","title":"Viewing the Class path","text":"<p>Clojure compiles to Java bytecode that runs on the JVM, so that code needs to be available in the Java class path.</p> <p>Note Look at the class path for your project</p> <p>The directory where the Clojure compiler will create the .class files for the current project.  All .class files must be on the class path otherwise the Clojure run time environment will not know they exist.</p> <pre><code>*compile-path*\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/whats-my-environment/#namespace","title":"Namespace","text":"<p>A namespace in clojure is a way to separate functions and data structures into logical components (similar to Java packages).  A <code>clojure.lang.Namespace</code> object representing the current namespace.</p> <p>Note Find out the current namespace</p> <pre><code>*ns*\n</code></pre> <p></p>"},{"location":"reference/clojure-syntax/whats-my-environment/#last-3-values-in-the-repl","title":"Last 3 values in the REPL","text":"<p>You can also get the 3 most most recent values returned in the REPL.</p> <p>Note Evaluate the following three expressions in the REPL, then pull out the last three results</p> <pre><code>(+ 1 2 3)\n\n(+ 1 2 (+ 1 2) (+ 2 3))\n\n(str \"Java will be fully functional in version \" (+ 10 (rand-int 20))\n</code></pre> <p>Now get the last three values returned in the REPL</p> <pre><code>(str *1 *2 *3)\n</code></pre> <p></p> <p>Hint You can cycle through previous expressions entered into the REPL using the <code>Shift-UpArrow</code> keyboard shortcut</p>"},{"location":"reference/clojure-syntax/syntax/","title":"Clojure Syntax","text":"<p>The Clojure syntax is very small and is actually a data structure, defined as a list, <code>()</code>, with the first element of a list being a function call and all other elements arguments to that function.</p> <p>Examples are editable (using an embedded REPL) so feel free to experiment and watch as the return value changes as you change the code. Reload the page if you want to reset all the code back to the starting point.</p>"},{"location":"reference/clojure-syntax/syntax/#edn-based-notation","title":"edn based notation","text":"<p>The core Clojure syntax is defined in the extensible data notation (edn). edn demonstrates that Clojure code is defined as a series of data structures</p> <p>Clojure adds an execution model on top of edn to make a programming language and is a super-set of edn.</p> <p>edn is used as a data transfer format, especially for Datomic the Clojure transactional database</p> <ul> <li>A case for Clojure by James Reeves provides a great introduction to edn</li> </ul>"},{"location":"reference/clojure-syntax/syntax/#calling-functions","title":"Calling functions","text":"<p>The first element in a list, <code>()</code>, is treated as a call to a function. The examples show how to call functions with multiple arguments.</p> <pre><code>(+ 1 2)\n</code></pre> <pre><code>(+ 3 (* 2 (- 7 2) 4) (/ 16 4))\n</code></pre> <pre><code>(str \"Clojure is \" (- 2020 2007) \" years old\")\n</code></pre> <pre><code>(inc 1)\n</code></pre> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <pre><code>(filter odd? (range 11))\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintprefix-notation-and-parens","title":"Hint::Prefix notation and parens","text":"<p>Hugging code with <code>()</code> is a simple syntax to define the scope of code expressions.  No additional <code>;</code>, <code>,</code> or spaces are required.</p> <p>Treating the first element of a list as a function call is referred to as prefix notation, which greatly simplifies Clojure syntax.  Prefix notation makes mathematical expressions completely deterministic, eliminating the need for operator precedence.</p>"},{"location":"reference/clojure-syntax/syntax/#understanding-functions","title":"Understanding functions","text":"<p>Functions contain doc-strings describing what that function does. The <code>doc</code> function returns the doc-string of a particular function.  Most editors also support viewing of doc-strings as well as jumping to function definitions to view the source code</p> <pre><code>(doc doc)\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#strongly-typed-under-the-covers","title":"Strongly typed under the covers","text":"<p>Clojure is a dynamically typed language so types do not need to be explicitly defined, although type hints can be added for performance where required.</p> <p>Clojure is strongly typed and everything is a type underneath, relative to the host platform (Clojure uses Java types, ClojureScript uses JavaScript types).  The type of anything in Clojure can be returned using the <code>type</code> function.</p> <pre><code>(type 42)\n;; (type {:hash \"data\" :map \"more data\"})\n</code></pre> <pre><code>(type {:hash \"data\" :map \"more data\"})\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#modeling-data-with-collection-types","title":"Modeling data with Collection types","text":"<p>Clojure has 4 main collection types, all immutable (cannot change once created) and can contain any Clojure types.</p> <pre><code>(str \"lists used mainly \" (* 2 2) \" \" :code)\n</code></pre> <pre><code>[0 \"indexed\" :array (* 2 2) \"random-access\"]\n</code></pre> <pre><code>{:key \"value\" \"hash-map\" \"also referred to as dictionary\"}\n</code></pre> <pre><code>#{1 2 3 4 \"unique\" \"set\" \"of\" \"values\" \"unordered\" (* 3 9)}\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintpersistent-data-types","title":"Hint::Persistent data types","text":"<p>To change data in Clojure new copies are created rather than changing existing values.  The copies of data will share values from the original data that are common in both.  This sharing is called persistent data types and enables immutable data to be used efficiently.</p>"},{"location":"reference/clojure-syntax/syntax/#defining-names-for-values-vars","title":"Defining names for values (vars)","text":"<p>Names can be bound to any values, from simple values like numbers, collections or even function calls.  Using <code>def</code> is convenient way to create names for values that are shared in your code.</p> <p>evaluating a name will return the value it is bound to.</p> <pre><code>(def public-health-data\n  ({:date \"2020-01-01\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-02\" :confirmed-cases 23014 :recovery-percent 15}\n   {:date \"2020-01-03\" :confirmed-cases 23014 :recovery-percent 15}))\n\npublic-health-data\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#hintdef-for-shared-values-let-for-locally-scoped-values","title":"Hint::def for shared values, let for locally scoped values","text":"<p><code>let</code> function is used to bind names to values locally, such as within a function definition.  Names bound with <code>def</code> have namespace scope so can be used with any code in that namespace.</p>"},{"location":"reference/clojure-syntax/syntax/#using-data-structures","title":"Using data structures","text":"<p>Using the <code>map</code> and <code>inc</code> function, increment all the numbers in a vector</p> <pre><code>(map inc [1 2 3 4 5])\n</code></pre> <p>The above <code>map</code> function is roughly equivalent to the following expression</p> <pre><code>(conj [] (inc 1) (inc 2) (inc 3) (inc 4) (inc 5))\n</code></pre> <p>The <code>conj</code> function creates a new collection by combining a collection and one or more values.</p> <p><code>map</code> <code>reduce</code> <code>filter</code> are common functions for iterating through a collection / sequence of values</p> <pre><code>(map * [1 3 5 8 13 21] [3 5 8 13 21 34])\n</code></pre> <pre><code>(filter even? [1 3 5 8 13 21 34])\n</code></pre> <pre><code>(reduce + [31 28 30 31 30 31])\n</code></pre> <pre><code>(empty? [])\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#defining-custom-functions","title":"Defining custom functions","text":"<pre><code>(defn square-of\n  \"Calculates the square of a given number\"\n  [number]\n  (* number number))\n\n(square-of 9)\n</code></pre> <p>Function definitions can also be used within other expressions, useful for mapping custom functions over a collection</p> <pre><code>(map (fn [x] (* x x)) [1 2 3 4 5])\n</code></pre>"},{"location":"reference/clojure-syntax/syntax/#host-interoperability","title":"Host Interoperability","text":"<p>The REPL in this web page is running inside a JavaScript engine, so JavaScript functions can be used from within ClojureScript code (ClojureScript is Clojure that runs in JavaScript environments).</p> <p>In the box below, replace <code>()</code> with <code>(js/alert \"I am a pop-up alert\")</code></p> <pre><code>()\n</code></pre> <p>JavaScript libraries can be used with ClojureScript, such as React.js</p> <pre><code>(defn concentric-circles []\n  [:svg {:style {:border \"1px solid\"\n                 :background \"white\"\n                 :width \"150px\"\n                 :height \"150px\"}}\n   [:circle {:r 50, :cx 75, :cy 75, :fill \"green\"}]\n   [:circle {:r 25, :cx 75, :cy 75, :fill \"blue\"}]\n   [:path {:stroke-width 12\n           :stroke \"white\"\n           :fill \"none\"\n           :d \"M 30,40 C 100,40 50,110 120,110\"}]\n   [:path {:stroke-width 12\n           :stroke \"white\"\n           :fill \"none\"\n           :d \"M 75,75 C 50,90 50,110 35,110\"}]])\n</code></pre>"},{"location":"reference/jvm/","title":"Reference: Java Virtual Machine","text":"<p>Understand the configuration options for the Java Virtual machine (JVM) which Clojure is hosted upon.</p> <p>Overview of tools for monitoring and profiling Clojure applications running on the JVM, to ensure effective running of Clojure applications in production.</p> <ul> <li>Common JVM Options - for development and deployment</li> <li>JVM Profiling tools - understand resources and help diagnose run-time problems</li> </ul> <p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p>"},{"location":"reference/jvm/#display-resources-available-to-the-jvm","title":"Display resources available to the JVM","text":"<p><code>-XshowSettings:system</code> displays the resources the JVM believes it has access too when running any Java command and is a very simple diagnostic tool to start with.</p> <p>See the environment resources available to the JVM without running a Clojure or Java application:</p> <pre><code>java -XshowSettings:system -version\n</code></pre> <p></p> <p>Include <code>-XshowSettings:system</code> when running any Java command to provide simple diagnostics, e.g. when running a Clojure Uberjar</p> <pre><code>java -XshowSettings:system -jar practicalli-service.jar\n</code></pre> <p>Print resources in Container systems</p> <p><code>-XshowSettings:system</code> is especially useful for environments which may vary in resources available, such as containers (Docker, Kubernettes, etc.)</p>"},{"location":"reference/jvm/#jvm-option-types","title":"JVM option types","text":"<p><code>-X</code> - nonstandard VM options</p> <p><code>-XX</code> standard VM options</p> <p><code>-XX</code> options are not checked for validity, so are ignored if the VM does not recognize the option. Options can therefore be used across different VM versions without ensuring a particular level of the VM.</p> <p><code>-D</code> a system property for the application running on the JVM using a name=value</p>"},{"location":"reference/jvm/#java-modules","title":"Java Modules","text":"<p>Java 9 introduced modules to move features out of JVM itself and include them as optional modules.</p> <p>Before CLJS-2377 issue was resolved, ClojureScript (2017) depended on <code>java.xml.bind.DataTypeConverter</code>. <code>java.xml.bind package</code> was deprecated in Java 9 and moved to a non-default module.</p> <p>At that time, compiling a ClojureScript project without adding the java.xml.bind module would return the error:</p> <pre><code>&lt;Exception details&gt;\n...\nCaused by: java.lang.ClassNotFoundException: javax.xml.bind.DatatypeConverter\n</code></pre> <p><code>clojure J--add-modules \"java.xml.bind\"</code> command line option will include the module</p> <p><code>:jvm-opts [\"--add-modules\" \"java.xml.bind\"]</code> added to Clojure CLI deps.edn or Leiningen project.clj file will include the module.</p> <p><code>-Djdk.launcher.addmods=java.xml.bind</code> added to the <code>JAVA_TOOL_OPTIONS</code> environment variable (<code>jdk.launcher.addmods</code> <code>--add-modules</code> doesn\u2019t work in <code>JAVA_TOOL_OPTIONS</code>)</p>"},{"location":"reference/jvm/#unified-logging-sub-system","title":"Unified Logging sub-system","text":"<p><code>-Xlog</code> - JEP 158</p>"},{"location":"reference/jvm/#references","title":"References","text":"<ul> <li>Best practice for JVM Tuning with G1 GC</li> <li>Command Line Options - IBM SDK documentation</li> <li>Best HotSpot JVM Options and switches for Java 11 through Java 17</li> </ul>"},{"location":"reference/jvm/common-options/","title":"Common JVM Options","text":"<p>Examples of commonly used options for any language on the Java Virtual Machine (JVM).</p> <p>The JVM is excellent at self-optimising its performance.  Introducing specific options should only be done if specific resource or performance issues have been identified.</p> <p>Understanding memory usage has more options to diagnose out of memory errors, garbage collection pauses and JIT compilation</p> <p><code>JDK_JAVA_OPTIONS</code> Environment Variable</p> <p><code>JDK_JAVA_OPTIONS</code> is the official Environment Variable for setting options when calling <code>java</code>, <code>javac</code> and other Java commands to start running a Java Virtual Machine (Java version 9 onward).</p>"},{"location":"reference/jvm/common-options/#java-heap-size","title":"Java heap size","text":"<p>Java Ergonomics should provide sensible default options.  Performance analysis of the running code may show advantages of manually setting memory sizes.</p> <p>Set the initial heap size if memory usage will quickly grow</p> <p><code>-Xms</code> \u2013 start heap size for JVM, e.g. <code>-Xms2048m</code> sets an initial heap size of 2 GB</p> <p><code>-XX:InitialRAMPercentage=n</code> sets the initial heap as <code>n</code> percentage of total RAM</p> <p>Set the maximum heap size if usage is relatively high under normal conditions</p> <p><code>-Xmx</code> \u2013 maximum heap size of JVM, e.g. <code>-Xmx2048m</code></p> <p><code>-XX:MaxRAMPercentage=n</code> sets the maximum heap as <code>n</code> percentage of total RAM</p> <p><code>-Xss</code> - set java thread stack size</p> <p><code>-Xms</code> and <code>-Xmx</code> are commonly used together (where there is a know fixed value for memory resources).</p>"},{"location":"reference/jvm/common-options/#heap-and-garbage-collection","title":"Heap and garbage collection","text":"<p><code>-XX:MaxHeapFreeRatio</code> \u2013 maximum percentage of heap free after garbage collection to avoid shrinking.</p> <p><code>-XX:MinHeapFreeRatio</code> \u2013 minimum percentage of heap free after GC to avoid expansion</p> <p>VisualVM or JConsole can monitor the heap usage</p>"},{"location":"reference/jvm/common-options/#container-environments","title":"Container Environments","text":"<p><code>-XX:InitialRAMPercentage</code> and <code>-XX:MaxRAMPercentage</code> options should be used to set relative limits to the resources available from the host.</p> <p>Setting specific heap sizes with <code>-Xms</code> and <code>-Xmx</code> is strongly discouraged in Container environments, as resources available to the container from the host could change between deployments (e.g. a change in operational configuration in Kubernettes, etc.)</p>"},{"location":"reference/jvm/common-options/#stack-traces","title":"Stack traces","text":"<p><code>-XX:-OmitStackTraceInFastThrow</code> no StackTrace for implicit exceptions thrown by JVM, e.g. NullPointerException, ArithmeticException, ArrayIndexOutOfBoundsException, ArrayStoreException or ClassCastException.</p>"},{"location":"reference/jvm/common-options/#reflection","title":"Reflection","text":"<p><code>--illegal-access</code> option controls how deep reflection warnings are handled.</p> <ul> <li>permit (default) - generates warning only when the first illegal access was detected</li> <li>warn - emit warning after each illegal access detection</li> <li>debug - add stack trace to warning</li> <li>deny - like debug for the first detection, then killing the program.</li> </ul> <p>Java 16 deprecates <code>--illegal-access</code> flag, via work done for JEP403 - may still be useful for 3rd party Java libraries.</p>"},{"location":"reference/jvm/common-options/#enable-class-data-sharing","title":"Enable class data sharing","text":"<p><code>-Xshareclasses</code> enables class data sharing in a shared class cache.</p> <p>The JVM connects to an existing cache (creating a cache if none exist). Multiple caches specified by adding a sub-option to the <code>-Xshareclasses</code> option.</p>"},{"location":"reference/jvm/common-options/#handling-outofmemory-error","title":"Handling \u2018OutOfMemory\u2019 Error","text":"<p>Generating a Heap Dump for out of memory (OOM) issues is recommended for production systems, to provide data for a deep analysis of the problem.  Generating a heap dump does not add overhead to the running JVM.</p> <p><code>-XX:+HeapDumpOnOutOfMemoryError</code> - trigger heap dump on out of memory failure</p> <p><code>-XX:HeapDumpPath=path-to-heap-dump-directory</code> - sets path to write the heap dump file (defaults to directory in which java command was ran from)</p> <p>A heap dump file can gigabytes in size, so assure that the target file system has sufficient capacity.</p> <p><code>-XX:OnOutOfMemoryError=\"shutdown -r\"</code> - restart the process immediately after out of memory failure</p> <p>The option can take multiple commands, separated by a <code>;</code>, e.g. <code>-XX:OnOutOfMemoryError=\"&lt; cmd args &gt;;&lt; cmd args &gt;\"</code></p>"},{"location":"reference/jvm/common-options/#trace-classloading-and-unloading","title":"Trace classloading and unloading","text":"<p>Identify memory leaks suspected from the JVM Class Loader, e.g. classes are not unloading or garbage collected</p> <p><code>-XX:+TraceClassLoading</code>  - log classes loaded into the JVM</p> <p><code>-XX:+TraceClassUnloading</code> - log classes unloaded from the JVM</p>"},{"location":"reference/jvm/common-options/#profiling","title":"Profiling","text":"<p>Profiling JVM processes provides a fine-grained view of application execution and resource utilization. Monitor parameters including Method Executions, Thread Executions, Garbage Collections and Object Creations.</p> <ul> <li><code>-Xprof</code></li> <li><code>-Xrunhprof</code></li> </ul> <p>Consider using a profile tool, such as VisualVM</p> <p></p>"},{"location":"reference/jvm/common-options/#skip-byte-code-verification","title":"Skip byte code verification","text":"<p>The byte code for each class loaded by the JVM Class Loader is verified, which is a relatively expensive task at startup. Adding classes on the boot classpath skips the cost of the verification, although also introduces a security risk so should only be used when classes have been previously verified.</p> <ul> <li><code>-Xbootclasspath</code> specifies classpath entries to load without verification</li> </ul> <p>Profiling an application is a more suitable long term solution than skipping byte code verification</p> <p>Checks carried out by the verifier include</p> <ul> <li>Uninitialized Variables</li> <li>Access rules for private data and methods are not violated</li> <li>Method calls match the object Reference</li> <li>There are no operand stack overflows or under-flows</li> <li>Arguments to all JVM instructions are valid types</li> <li>Final classes are not subclassed and final methods are not overridden</li> <li>field and method references have valid names, valid classes and valid type descriptor</li> </ul>"},{"location":"reference/jvm/common-options/#print-gc","title":"Print GC","text":"<p>Enable the garbage collection logging to capture detailed statistics, e.g. type of garbage collector, how often memory is restored and how much time memory was held for. Garbage collection can last several milliseconds, so logging is useful for latency-sensitive processes.</p> <ul> <li><code>-verbose:gc</code> - logs garbage collector runs and how long they're taking.</li> <li><code>-XX:+PrintGCDetails</code> - includes the data from -verbose:gc but also adds information about the size of the new generation and more accurate timings.</li> <li><code>-XX:-PrintGCTimeStamps</code> - Print timestamps at garbage collection.</li> </ul> <p>Consider using LMAX disruptor for a Garbage Collection free architecture for ultra latency-sensitive applications</p>"},{"location":"reference/jvm/common-options/#deprecated-permgen-size","title":"Deprecated: PermGen Size","text":"<p><code>-XX:PermSize</code> - size of PermGen space where string pool and class metadata is saved.</p> <p>Option is useful for web servers which load classes of a web application during deployment (e.g. deploying a jar or war to Tomcat).</p> <p>Metaspace has taken over PermGen space in Java 8 onward</p>"},{"location":"reference/jvm/experimental-options/","title":"Reference: JVM Experimental Options","text":"<p>The HotSpot JVM provides the opportunity to try features that may appear in future release, although are currently not production-ready.</p> <p>HotSpot JVM experimental features need to be unlocked by specifying the <code>-XX:+UnlockExperimentalVMOptions</code> option.</p> <p>For example, the ZGC garbage collector in JDK 11 can be accessed using</p> <pre><code>java -XX:+UnlockExperimentalVMOptions -XX:+UseZGC\n</code></pre> <p>The ZGC collector became a product option in JDK 15, so is no longer experimental.</p>"},{"location":"reference/jvm/experimental-options/#manageable","title":"Manageable","text":"<p>Show locks held by <code>java.util.concurrent</code> classes in a HotSpot JVM thread dump:</p> <pre><code>java -XX:+UnlockExperimentalVMOptions -XX:+PrintConcurrentLocks\n</code></pre> <p>These options can be set at runtime via the MXBean API or related JDK tools</p>"},{"location":"reference/jvm/experimental-options/#diagnostic","title":"Diagnostic","text":"<p>Accessing advanced diagnostic information about the HotSpot JVM.</p> <p>These options require you to use the <code>-XX:+UnlockDiagnosticVMOptions</code>  option before they can be used.</p> <p>View advance compilation optimisations using the <code>-XX:+LogCompilation</code> option:</p> <pre><code>java -XX:+UnlockDiagnosticVMOptions -XX:+LogCompilation\n</code></pre> <p>The HotSpot JVM outputs a log file containing details of all the optimisations made by the JIT compilers. Inspect the output to understand which parts of your program were optimized and to identify parts of the program that might not have been optimized as expected.</p> <p>The LogCompilation output is verbose but can be visualized in a tool such as JITWatch, which can tell you about method inlining, escape analysis, lock elision, and other optimizations that the HotSpot JVM made to your running code.</p>"},{"location":"reference/jvm/java-17-flags/","title":"Reference: Java 17 JVM flags","text":"<p>A complete list of all flags available for the JVM, created using the <code>-XX:+PrintFlagsFinal</code> option and the results written to a file</p> <pre><code>java -XX:+PrintFlagsFinal &gt; java-flags.md\n</code></pre> <p>Find specific flags by using grep on the output with a name</p> <pre><code>java -XX:+PrintFlagsFinal -version | grep MaxHeap\n</code></pre> Type Name Units ? ? uintx MaxHeapFreeRatio 70 {manageable} {default} size_t MaxHeapSize 8342470656 {product} {ergonomic} size_t SoftMaxHeapSize 8342470656 {manageable} {ergonomic}"},{"location":"reference/jvm/java-17-flags/#full-list-of-jvm-flags","title":"Full list of JVM flags","text":"Type Option Name Default value Product Category int ActiveProcessorCount -1 {product} {default} uintx AdaptiveSizeDecrementScaleFactor 4 {product} {default} uintx AdaptiveSizeMajorGCDecayTimeScale 10 {product} {default} uintx AdaptiveSizePolicyCollectionCostMargin 50 {product} {default} uintx AdaptiveSizePolicyInitializingSteps 20 {product} {default} uintx AdaptiveSizePolicyOutputInterval 0 {product} {default} uintx AdaptiveSizePolicyWeight 10 {product} {default} uintx AdaptiveSizeThroughPutPolicy 0 {product} {default} uintx AdaptiveTimeWeight 25 {product} {default} bool AdjustStackSizeForTLS false {product} {default} bool AggressiveHeap false {product} {default} intx AliasLevel 3 {C2 product} {default} bool AlignVector false {C2 product} {default} ccstr AllocateHeapAt {product} {default} intx AllocateInstancePrefetchLines 1 {product} {default} intx AllocatePrefetchDistance 256 {product} {default} intx AllocatePrefetchInstr 0 {product} {default} intx AllocatePrefetchLines 3 {product} {default} intx AllocatePrefetchStepSize 64 {product} {default} intx AllocatePrefetchStyle 1 {product} {default} bool AllowParallelDefineClass false {product} {default} bool AllowRedefinitionToAddDeleteMethods false {product} {default} bool AllowUserSignalHandlers false {product} {default} bool AllowVectorizeOnDemand true {C2 product} {default} bool AlwaysActAsServerClassMachine false {product} {default} bool AlwaysCompileLoopMethods false {product} {default} bool AlwaysLockClassLoader false {product} {default} bool AlwaysPreTouch false {product} {default} bool AlwaysRestoreFPU false {product} {default} bool AlwaysTenure false {product} {default} ccstr ArchiveClassesAtExit {product} {default} intx ArrayCopyLoadStoreMaxElem 8 {C2 product} {default} size_t AsyncLogBufferSize 2097152 {product} {default} intx AutoBoxCacheMax 128 {C2 product} {default} intx BCEATraceLevel 0 {product} {default} bool BackgroundCompilation true {pd product} {default} size_t BaseFootPrintEstimate 268435456 {product} {default} intx BiasedLockingBulkRebiasThreshold 20 {product} {default} intx BiasedLockingBulkRevokeThreshold 40 {product} {default} intx BiasedLockingDecayTime 25000 {product} {default} intx BiasedLockingStartupDelay 0 {product} {default} bool BlockLayoutByFrequency true {C2 product} {default} intx BlockLayoutMinDiamondPercentage 20 {C2 product} {default} bool BlockLayoutRotateLoops true {C2 product} {default} intx C1InlineStackLimit 5 {C1 product} {default} intx C1MaxInlineLevel 9 {C1 product} {default} intx C1MaxInlineSize 35 {C1 product} {default} intx C1MaxRecursiveInlineLevel 1 {C1 product} {default} intx C1MaxTrivialSize 6 {C1 product} {default} bool C1OptimizeVirtualCallProfiling true {C1 product} {default} bool C1ProfileBranches true {C1 product} {default} bool C1ProfileCalls true {C1 product} {default} bool C1ProfileCheckcasts true {C1 product} {default} bool C1ProfileInlinedCalls true {C1 product} {default} bool C1ProfileVirtualCalls true {C1 product} {default} bool C1UpdateMethodData true {C1 product} {default} intx CICompilerCount 12 {product} {ergonomic} bool CICompilerCountPerCPU true {product} {default} bool CITime false {product} {default} bool CheckJNICalls false {product} {default} bool ClassUnloading true {product} {default} bool ClassUnloadingWithConcurrentMark true {product} {default} bool ClipInlining true {product} {default} uintx CodeCacheExpansionSize 65536 {pd product} {default} bool CompactStrings true {pd product} {default} ccstr CompilationMode default {product} {default} ccstrlist CompileCommand {product} {default} ccstr CompileCommandFile {product} {default} ccstrlist CompileOnly {product} {default} intx CompileThreshold 10000 {pd product} {default} double CompileThresholdScaling 1.000000 {product} {default} intx CompilerThreadPriority -1 {product} {default} intx CompilerThreadStackSize 1024 {pd product} {default} size_t CompressedClassSpaceSize 1073741824 {product} {default} uint ConcGCThreads 3 {product} {ergonomic} intx ConditionalMoveLimit 3 {C2 pd product} {default} intx ContendedPaddingWidth 128 {product} {default} bool CrashOnOutOfMemoryError false {product} {default} bool CreateCoredumpOnCrash true {product} {default} bool CriticalJNINatives false {product} {default} bool DTraceAllocProbes false {product} {default} bool DTraceMethodProbes false {product} {default} bool DTraceMonitorProbes false {product} {default} bool DisableAttachMechanism false {product} {default} bool DisableExplicitGC false {product} {default} bool DisplayVMOutputToStderr false {product} {default} bool DisplayVMOutputToStdout false {product} {default} bool DoEscapeAnalysis true {C2 product} {default} bool DoReserveCopyInSuperWord true {C2 product} {default} bool DontCompileHugeMethods true {product} {default} bool DontYieldALot false {pd product} {default} ccstr DumpLoadedClassList {product} {default} bool DumpReplayDataOnError true {product} {default} bool DumpSharedSpaces false {product} {default} bool DynamicDumpSharedSpaces false {product} {default} bool EagerXrunInit false {product} {default} intx EliminateAllocationArraySizeLimit 64 {C2 product} {default} bool EliminateAllocations true {C2 product} {default} bool EliminateAutoBox true {C2 product} {default} bool EliminateLocks true {C2 product} {default} bool EliminateNestedLocks true {C2 product} {default} bool EnableContended true {product} {default} bool EnableDynamicAgentLoading true {product} {default} size_t ErgoHeapSizeLimit 0 {product} {default} ccstr ErrorFile {product} {default} bool ErrorFileToStderr false {product} {default} bool ErrorFileToStdout false {product} {default} uint64_t ErrorLogTimeout 120 {product} {default} double EscapeAnalysisTimeout 20.000000 {C2 product} {default} bool EstimateArgEscape true {product} {default} bool ExecutingUnitTests false {product} {default} bool ExitOnOutOfMemoryError false {product} {default} bool ExplicitGCInvokesConcurrent false {product} {default} bool ExtendedDTraceProbes false {product} {default} bool ExtensiveErrorReports false {product} {default} ccstr ExtraSharedClassListFile {product} {default} bool FilterSpuriousWakeups true {product} {default} bool FlightRecorder false {product} {default} ccstr FlightRecorderOptions {product} {default} bool ForceTimeHighResolution false {product} {default} intx FreqInlineSize 325 {C2 pd product} {default} double G1ConcMarkStepDurationMillis 10.000000 {product} {default} uintx G1ConcRSHotCardLimit 4 {product} {default} size_t G1ConcRSLogCacheSize 10 {product} {default} size_t G1ConcRefinementGreenZone 0 {product} {default} size_t G1ConcRefinementRedZone 0 {product} {default} uintx G1ConcRefinementServiceIntervalMillis 300 {product} {default} uint G1ConcRefinementThreads 13 {product} {ergonomic} size_t G1ConcRefinementThresholdStep 2 {product} {default} size_t G1ConcRefinementYellowZone 0 {product} {default} uintx G1ConfidencePercent 50 {product} {default} size_t G1HeapRegionSize 4194304 {product} {ergonomic} uintx G1HeapWastePercent 5 {product} {default} uintx G1MixedGCCountTarget 8 {product} {default} uintx G1PeriodicGCInterval 0 {manageable} {default} bool G1PeriodicGCInvokesConcurrent true {product} {default} double G1PeriodicGCSystemLoadThreshold 0.000000 {manageable} {default} intx G1RSetRegionEntries 768 {product} {default} intx G1RSetSparseRegionEntries 32 {product} {default} intx G1RSetUpdatingPauseTimePercent 10 {product} {default} uint G1RefProcDrainInterval 1000 {product} {default} uintx G1ReservePercent 10 {product} {default} uintx G1SATBBufferEnqueueingThresholdPercent 60 {product} {default} size_t G1SATBBufferSize 1024 {product} {default} size_t G1UpdateBufferSize 256 {product} {default} bool G1UseAdaptiveConcRefinement true {product} {default} bool G1UseAdaptiveIHOP true {product} {default} uintx GCDrainStackTargetSize 64 {product} {ergonomic} uintx GCHeapFreeLimit 2 {product} {default} uintx GCLockerEdenExpansionPercent 5 {product} {default} uintx GCPauseIntervalMillis 201 {product} {default} uintx GCTimeLimit 98 {product} {default} uintx GCTimeRatio 12 {product} {default} size_t HeapBaseMinAddress 2147483648 {pd product} {default} bool HeapDumpAfterFullGC false {manageable} {default} bool HeapDumpBeforeFullGC false {manageable} {default} intx HeapDumpGzipLevel 0 {manageable} {default} bool HeapDumpOnOutOfMemoryError false {manageable} {default} ccstr HeapDumpPath {manageable} {default} uintx HeapFirstMaximumCompactionCount 3 {product} {default} uintx HeapMaximumCompactionInterval 20 {product} {default} uintx HeapSearchSteps 3 {product} {default} size_t HeapSizePerGCThread 43620760 {product} {default} bool IgnoreEmptyClassPaths false {product} {default} bool IgnoreUnrecognizedVMOptions false {product} {default} uintx IncreaseFirstTierCompileThresholdAt 50 {product} {default} bool IncrementalInline true {C2 product} {default} uintx InitialCodeCacheSize 2555904 {pd product} {default} size_t InitialHeapSize 490733568 {product} {ergonomic} uintx InitialRAMFraction 64 {product} {default} double InitialRAMPercentage 1.562500 {product} {default} uintx InitialSurvivorRatio 8 {product} {default} uintx InitialTenuringThreshold 7 {product} {default} uintx InitiatingHeapOccupancyPercent 45 {product} {default} bool Inline true {product} {default} ccstr InlineDataFile {product} {default} intx InlineSmallCode 2500 {C2 pd product} {default} bool InlineSynchronizedMethods true {C1 product} {default} intx InteriorEntryAlignment 16 {C2 pd product} {default} intx InterpreterProfilePercentage 33 {product} {default} bool JavaMonitorsInStackTrace true {product} {default} intx JavaPriority10_To_OSPriority -1 {product} {default} intx JavaPriority1_To_OSPriority -1 {product} {default} intx JavaPriority2_To_OSPriority -1 {product} {default} intx JavaPriority3_To_OSPriority -1 {product} {default} intx JavaPriority4_To_OSPriority -1 {product} {default} intx JavaPriority5_To_OSPriority -1 {product} {default} intx JavaPriority6_To_OSPriority -1 {product} {default} intx JavaPriority7_To_OSPriority -1 {product} {default} intx JavaPriority8_To_OSPriority -1 {product} {default} intx JavaPriority9_To_OSPriority -1 {product} {default} size_t LargePageHeapSizeThreshold 134217728 {product} {default} size_t LargePageSizeInBytes 0 {product} {default} intx LiveNodeCountInliningCutoff 40000 {C2 product} {default} bool LoadExecStackDllInVMThread true {product} {default} intx LoopMaxUnroll 16 {C2 product} {default} intx LoopOptsCount 43 {C2 product} {default} intx LoopPercentProfileLimit 30 {C2 pd product} {default} uintx LoopStripMiningIter 1000 {C2 product} {default} uintx LoopStripMiningIterShortLoop 100 {C2 product} {default} intx LoopUnrollLimit 60 {C2 pd product} {default} intx LoopUnrollMin 4 {C2 product} {default} bool LoopUnswitching true {C2 product} {default} bool ManagementServer false {product} {default} size_t MarkStackSize 4194304 {product} {ergonomic} size_t MarkStackSizeMax 536870912 {product} {default} uint MarkSweepAlwaysCompactCount 4 {product} {default} uintx MarkSweepDeadRatio 5 {product} {default} intx MaxBCEAEstimateLevel 5 {product} {default} intx MaxBCEAEstimateSize 150 {product} {default} uint64_t MaxDirectMemorySize 0 {product} {default} bool MaxFDLimit true {product} {default} uintx MaxGCMinorPauseMillis 18446744073709551615 {product} {default} uintx MaxGCPauseMillis 200 {product} {default} uintx MaxHeapFreeRatio 70 {manageable} {default} size_t MaxHeapSize 7818182656 {product} {ergonomic} intx MaxInlineLevel 15 {C2 product} {default} intx MaxInlineSize 35 {C2 product} {default} intx MaxJNILocalCapacity 65536 {product} {default} intx MaxJavaStackTraceDepth 1024 {product} {default} intx MaxJumpTableSize 65000 {C2 product} {default} intx MaxJumpTableSparseness 5 {C2 product} {default} intx MaxLabelRootDepth 1100 {C2 product} {default} intx MaxLoopPad 15 {C2 product} {default} size_t MaxMetaspaceExpansion 5439488 {product} {default} uintx MaxMetaspaceFreeRatio 70 {product} {default} size_t MaxMetaspaceSize 18446744073709551615 {product} {default} size_t MaxNewSize 4689231872 {product} {ergonomic} intx MaxNodeLimit 80000 {C2 product} {default} uint64_t MaxRAM 137438953472 {pd product} {default} uintx MaxRAMFraction 4 {product} {default} double MaxRAMPercentage 25.000000 {product} {default} intx MaxRecursiveInlineLevel 1 {C2 product} {default} uintx MaxTenuringThreshold 15 {product} {default} intx MaxTrivialSize 6 {C2 product} {default} intx MaxVectorSize 32 {C2 product} {default} ccstr MetaspaceReclaimPolicy balanced {product} {default} size_t MetaspaceSize 22020096 {product} {default} bool MethodFlushing true {product} {default} size_t MinHeapDeltaBytes 4194304 {product} {ergonomic} uintx MinHeapFreeRatio 40 {manageable} {default} size_t MinHeapSize 8388608 {product} {ergonomic} intx MinInliningThreshold 250 {product} {default} intx MinJumpTableSize 10 {C2 pd product} {default} size_t MinMetaspaceExpansion 327680 {product} {default} uintx MinMetaspaceFreeRatio 40 {product} {default} uintx MinRAMFraction 2 {product} {default} double MinRAMPercentage 50.000000 {product} {default} uintx MinSurvivorRatio 3 {product} {default} size_t MinTLABSize 2048 {product} {default} intx MultiArrayExpandLimit 6 {C2 product} {default} uintx NUMAChunkResizeWeight 20 {product} {default} size_t NUMAInterleaveGranularity 2097152 {product} {default} uintx NUMAPageScanRate 256 {product} {default} size_t NUMASpaceResizeRate 1073741824 {product} {default} bool NUMAStats false {product} {default} ccstr NativeMemoryTracking off {product} {default} bool NeverActAsServerClassMachine false {pd product} {default} bool NeverTenure false {product} {default} uintx NewRatio 2 {product} {default} size_t NewSize 1363144 {product} {default} size_t NewSizeThreadIncrease 5320 {pd product} {default} intx NmethodSweepActivity 10 {product} {default} intx NodeLimitFudgeFactor 2000 {C2 product} {default} uintx NonNMethodCodeHeapSize 7602480 {pd product} {ergonomic} uintx NonProfiledCodeHeapSize 122027880 {pd product} {ergonomic} intx NumberOfLoopInstrToAlign 4 {C2 product} {default} intx ObjectAlignmentInBytes 8 {product lp64_product} {default} size_t OldPLABSize 1024 {product} {default} size_t OldSize 5452592 {product} {default} bool OmitStackTraceInFastThrow true {product} {default} ccstrlist OnError {product} {default} ccstrlist OnOutOfMemoryError {product} {default} intx OnStackReplacePercentage 140 {pd product} {default} bool OptimizeFill false {C2 product} {default} bool OptimizePtrCompare true {C2 product} {default} bool OptimizeStringConcat true {C2 product} {default} bool OptoBundling false {C2 pd product} {default} intx OptoLoopAlignment 16 {pd product} {default} bool OptoRegScheduling true {C2 pd product} {default} bool OptoScheduling false {C2 pd product} {default} uintx PLABWeight 75 {product} {default} bool PSChunkLargeArrays true {product} {default} int ParGCArrayScanChunk 50 {product} {default} uintx ParallelGCBufferWastePct 10 {product} {default} uint ParallelGCThreads 13 {product} {default} size_t ParallelOldDeadWoodLimiterMean 50 {product} {default} size_t ParallelOldDeadWoodLimiterStdDev 80 {product} {default} bool ParallelRefProcBalancingEnabled true {product} {default} bool ParallelRefProcEnabled true {product} {default} bool PartialPeelAtUnsignedTests true {C2 product} {default} bool PartialPeelLoop true {C2 product} {default} intx PartialPeelNewPhiDelta 0 {C2 product} {default} uintx PausePadding 1 {product} {default} intx PerBytecodeRecompilationCutoff 200 {product} {default} intx PerBytecodeTrapLimit 4 {product} {default} intx PerMethodRecompilationCutoff 400 {product} {default} intx PerMethodTrapLimit 100 {product} {default} bool PerfAllowAtExitRegistration false {product} {default} bool PerfBypassFileSystemCheck false {product} {default} intx PerfDataMemorySize 32768 {product} {default} intx PerfDataSamplingInterval 50 {product} {default} ccstr PerfDataSaveFile {product} {default} bool PerfDataSaveToFile false {product} {default} bool PerfDisableSharedMem false {product} {default} intx PerfMaxStringConstLength 1024 {product} {default} size_t PreTouchParallelChunkSize 4194304 {pd product} {default} bool PreferContainerQuotaForCPUCount true {product} {default} bool PreferInterpreterNativeStubs false {pd product} {default} intx PrefetchCopyIntervalInBytes 576 {product} {default} intx PrefetchFieldsAhead 1 {product} {default} intx PrefetchScanIntervalInBytes 576 {product} {default} bool PreserveAllAnnotations false {product} {default} bool PreserveFramePointer false {pd product} {default} size_t PretenureSizeThreshold 0 {product} {default} bool PrintClassHistogram false {manageable} {default} bool PrintCodeCache false {product} {default} bool PrintCodeCacheOnCompilation false {product} {default} bool PrintCommandLineFlags false {product} {default} bool PrintCompilation false {product} {default} bool PrintConcurrentLocks false {manageable} {default} bool PrintExtendedThreadInfo false {product} {default} bool PrintFlagsFinal true {product} {command line} bool PrintFlagsInitial false {product} {default} bool PrintFlagsRanges false {product} {default} bool PrintGC false {product} {default} bool PrintGCDetails false {product} {default} bool PrintHeapAtSIGBREAK true {product} {default} bool PrintSharedArchiveAndExit false {product} {default} bool PrintSharedDictionary false {product} {default} bool PrintStringTableStatistics false {product} {default} bool PrintTieredEvents false {product} {default} bool PrintVMOptions false {product} {default} bool PrintWarnings true {product} {default} uintx ProcessDistributionStride 4 {product} {default} bool ProfileInterpreter true {pd product} {default} intx ProfileMaturityPercentage 20 {product} {default} uintx ProfiledCodeHeapSize 122027880 {pd product} {ergonomic} uintx PromotedPadding 3 {product} {default} uintx QueuedAllocationWarningCount 0 {product} {default} int RTMRetryCount 5 {ARCH product} {default} bool RangeCheckElimination true {product} {default} bool ReassociateInvariants true {C2 product} {default} bool RecordDynamicDumpInfo false {product} {default} bool ReduceBulkZeroing true {C2 product} {default} bool ReduceFieldZeroing true {C2 product} {default} bool ReduceInitialCardMarks true {C2 product} {default} bool ReduceSignalUsage false {product} {default} intx RefDiscoveryPolicy 0 {product} {default} bool RegisterFinalizersAtInit true {product} {default} bool RelaxAccessControlCheck false {product} {default} ccstr ReplayDataFile {product} {default} bool RequireSharedSpaces false {product} {default} uintx ReservedCodeCacheSize 251658240 {pd product} {ergonomic} bool ResizePLAB true {product} {default} bool ResizeTLAB true {product} {default} bool RestoreMXCSROnJNICalls false {product} {default} bool RestrictContended true {product} {default} bool RestrictReservedStack true {product} {default} bool RewriteBytecodes true {pd product} {default} bool RewriteFrequentPairs true {pd product} {default} bool SafepointTimeout false {product} {default} intx SafepointTimeoutDelay 10000 {product} {default} bool ScavengeBeforeFullGC false {product} {default} bool SegmentedCodeCache true {product} {ergonomic} intx SelfDestructTimer 0 {product} {default} ccstr SharedArchiveConfigFile {product} {default} ccstr SharedArchiveFile {product} {default} size_t SharedBaseAddress 34359738368 {product} {default} ccstr SharedClassListFile {product} {default} uintx SharedSymbolTableBucketSize 4 {product} {default} ccstr ShenandoahGCHeuristics adaptive {product} {default} ccstr ShenandoahGCMode satb {product} {default} bool ShowCodeDetailsInExceptionMessages true {manageable} {default} bool ShowMessageBoxOnError false {product} {default} bool ShrinkHeapInSteps true {product} {default} size_t SoftMaxHeapSize 7818182656 {manageable} {ergonomic} intx SoftRefLRUPolicyMSPerMB 1000 {product} {default} bool SplitIfBlocks true {C2 product} {default} intx StackRedPages 1 {pd product} {default} intx StackReservedPages 1 {pd product} {default} intx StackShadowPages 20 {pd product} {default} bool StackTraceInThrowable true {product} {default} intx StackYellowPages 2 {pd product} {default} uintx StartAggressiveSweepingAt 10 {product} {default} bool StartAttachListener false {product} {default} ccstr StartFlightRecording {product} {default} uint StringDeduplicationAgeThreshold 3 {product} {default} uintx StringTableSize 65536 {product} {default} bool SuperWordLoopUnrollAnalysis true {C2 pd product} {default} bool SuperWordReductions true {C2 product} {default} bool SuppressFatalErrorMessage false {product} {default} uintx SurvivorPadding 3 {product} {default} uintx SurvivorRatio 8 {product} {default} double SweeperThreshold 0.500000 {product} {default} uintx TLABAllocationWeight 35 {product} {default} uintx TLABRefillWasteFraction 64 {product} {default} size_t TLABSize 0 {product} {default} bool TLABStats true {product} {default} uintx TLABWasteIncrement 4 {product} {default} uintx TLABWasteTargetPercent 1 {product} {default} uintx TargetPLABWastePct 10 {product} {default} uintx TargetSurvivorRatio 50 {product} {default} uintx TenuredGenerationSizeIncrement 20 {product} {default} uintx TenuredGenerationSizeSupplement 80 {product} {default} uintx TenuredGenerationSizeSupplementDecay 2 {product} {default} intx ThreadPriorityPolicy 0 {product} {default} bool ThreadPriorityVerbose false {product} {default} intx ThreadStackSize 1024 {pd product} {default} uintx ThresholdTolerance 10 {product} {default} intx Tier0BackedgeNotifyFreqLog 10 {product} {default} intx Tier0InvokeNotifyFreqLog 7 {product} {default} intx Tier0ProfilingStartPercentage 200 {product} {default} intx Tier23InlineeNotifyFreqLog 20 {product} {default} intx Tier2BackEdgeThreshold 0 {product} {default} intx Tier2BackedgeNotifyFreqLog 14 {product} {default} intx Tier2CompileThreshold 0 {product} {default} intx Tier2InvokeNotifyFreqLog 11 {product} {default} intx Tier3BackEdgeThreshold 60000 {product} {default} intx Tier3BackedgeNotifyFreqLog 13 {product} {default} intx Tier3CompileThreshold 2000 {product} {default} intx Tier3DelayOff 2 {product} {default} intx Tier3DelayOn 5 {product} {default} intx Tier3InvocationThreshold 200 {product} {default} intx Tier3InvokeNotifyFreqLog 10 {product} {default} intx Tier3LoadFeedback 5 {product} {default} intx Tier3MinInvocationThreshold 100 {product} {default} intx Tier4BackEdgeThreshold 40000 {product} {default} intx Tier4CompileThreshold 15000 {product} {default} intx Tier4InvocationThreshold 5000 {product} {default} intx Tier4LoadFeedback 3 {product} {default} intx Tier4MinInvocationThreshold 600 {product} {default} bool TieredCompilation true {pd product} {default} intx TieredCompileTaskTimeout 50 {product} {default} intx TieredRateUpdateMaxTime 25 {product} {default} intx TieredRateUpdateMinTime 1 {product} {default} intx TieredStopAtLevel 4 {product} {default} bool TimeLinearScan false {C1 product} {default} ccstr TraceJVMTI {product} {default} intx TrackedInitializationLimit 50 {C2 product} {default} bool TrapBasedNullChecks false {pd product} {default} bool TrapBasedRangeChecks false {C2 pd product} {default} intx TypeProfileArgsLimit 2 {product} {default} uintx TypeProfileLevel 111 {pd product} {default} intx TypeProfileMajorReceiverPercent 90 {C2 product} {default} intx TypeProfileParmsLimit 2 {product} {default} intx TypeProfileWidth 2 {product} {default} intx UnguardOnExecutionViolation 0 {product} {default} bool UseAES true {product} {default} intx UseAVX 2 {ARCH product} {default} bool UseAdaptiveGenerationSizePolicyAtMajorCollection true {product} {default} bool UseAdaptiveGenerationSizePolicyAtMinorCollection true {product} {default} bool UseAdaptiveNUMAChunkSizing true {product} {default} bool UseAdaptiveSizeDecayMajorGCCost true {product} {default} bool UseAdaptiveSizePolicy true {product} {default} bool UseAdaptiveSizePolicyFootprintGoal true {product} {default} bool UseAdaptiveSizePolicyWithSystemGC false {product} {default} bool UseAddressNop true {ARCH product} {default} bool UseBASE64Intrinsics false {product} {default} bool UseBMI1Instructions true {ARCH product} {default} bool UseBMI2Instructions true {ARCH product} {default} bool UseBiasedLocking false {product} {default} bool UseBimorphicInlining true {C2 product} {default} bool UseCLMUL true {ARCH product} {default} bool UseCMoveUnconditionally false {C2 product} {default} bool UseCodeAging true {product} {default} bool UseCodeCacheFlushing true {product} {default} bool UseCompiler true {product} {default} bool UseCompressedClassPointers true {product lp64_product} {ergonomic} bool UseCompressedOops true {product lp64_product} {ergonomic} bool UseCondCardMark false {product} {default} bool UseContainerSupport true {product} {default} bool UseCountLeadingZerosInstruction true {ARCH product} {default} bool UseCountTrailingZerosInstruction true {ARCH product} {default} bool UseCountedLoopSafepoints true {C2 product} {default} bool UseCounterDecay true {product} {default} bool UseDivMod true {C2 product} {default} bool UseDynamicNumberOfCompilerThreads true {product} {default} bool UseDynamicNumberOfGCThreads true {product} {default} bool UseEmptySlotsInSupers true {product} {default} bool UseFMA true {product} {default} bool UseFPUForSpilling true {C2 product} {default} bool UseFastJNIAccessors true {product} {default} bool UseFastStosb false {ARCH product} {default} bool UseG1GC true {product} {ergonomic} bool UseGCOverheadLimit true {product} {default} bool UseHeavyMonitors false {product} {default} bool UseHugeTLBFS false {product} {default} bool UseInlineCaches true {product} {default} bool UseInterpreter true {product} {default} bool UseJumpTables true {C2 product} {default} bool UseLargePages false {pd product} {default} bool UseLargePagesIndividualAllocation false {pd product} {default} bool UseLinuxPosixThreadCPUClocks true {product} {default} bool UseLoopCounter true {product} {default} bool UseLoopInvariantCodeMotion true {C1 product} {default} bool UseLoopPredicate true {C2 product} {default} bool UseMaximumCompactionOnSystemGC true {product} {default} bool UseNUMA false {product} {default} bool UseNUMAInterleaving false {product} {default} bool UseNewLongLShift true {ARCH product} {default} bool UseNotificationThread true {product} {default} bool UseOnStackReplacement true {pd product} {default} bool UseOnlyInlinedBimorphic true {C2 product} {default} bool UseOprofile false {product} {default} bool UseOptoBiasInlining false {C2 product} {default} bool UsePSAdaptiveSurvivorSizePolicy true {product} {default} bool UseParallelGC false {product} {default} bool UsePerfData true {product} {default} bool UsePopCountInstruction true {product} {default} bool UseProfiledLoopPredicate true {C2 product} {default} bool UseRTMDeopt false {ARCH product} {default} bool UseRTMLocking false {ARCH product} {default} bool UseSHA true {product} {default} bool UseSHM false {product} {default} intx UseSSE 4 {ARCH product} {default} bool UseSSE42Intrinsics true {ARCH product} {default} bool UseSerialGC false {product} {default} bool UseSharedSpaces true {product} {default} bool UseShenandoahGC false {product} {default} bool UseSignalChaining true {product} {default} bool UseStoreImmI16 true {ARCH product} {default} bool UseStringDeduplication false {product} {default} bool UseSubwordForMaxVector true {C2 product} {default} bool UseSuperWord true {C2 product} {default} bool UseTLAB true {product} {default} bool UseThreadPriorities true {pd product} {default} bool UseTransparentHugePages false {product} {default} bool UseTypeProfile true {product} {default} bool UseTypeSpeculation true {C2 product} {default} bool UseUnalignedLoadStores true {ARCH product} {default} bool UseVectorCmov false {C2 product} {default} bool UseXMMForArrayCopy true {product} {default} bool UseXMMForObjInit true {ARCH product} {default} bool UseXmmI2D true {ARCH product} {default} bool UseXmmI2F true {ARCH product} {default} bool UseXmmLoadAndClearUpper true {ARCH product} {default} bool UseXmmRegToRegMoveAll true {ARCH product} {default} bool UseZGC false {product} {default} intx VMThreadPriority -1 {product} {default} intx VMThreadStackSize 1024 {pd product} {default} intx ValueMapInitialSize 11 {C1 product} {default} intx ValueMapMaxLoopSize 8 {C1 product} {default} intx ValueSearchLimit 1000 {C2 product} {default} bool VerifySharedSpaces false {product} {default} uintx YoungGenerationSizeIncrement 20 {product} {default} uintx YoungGenerationSizeSupplement 80 {product} {default} uintx YoungGenerationSizeSupplementDecay 8 {product} {default} size_t YoungPLABSize 4096 {product} {default} double ZAllocationSpikeTolerance 2.000000 {product} {default} double ZCollectionInterval 0.000000 {product} {default} double ZFragmentationLimit 25.000000 {product} {default} size_t ZMarkStackSpaceLimit 8589934592 {product} {default} bool ZProactive true {product} {default} bool ZUncommit true {product} {default} uintx ZUncommitDelay 300 {product} {default} bool ZeroTLAB false {product} {default}"},{"location":"reference/jvm/profile-tools/","title":"Profile JVM applications","text":"<p>Profile applications on the JVM, visualising memory and CPU resources, identifying bottlenecks and areas of the code to review to optimise a running application.</p> <p> Using FlameGraphs To Illuminate The JVM  A Simple Approach to the Advanced JVM Profiling</p>"},{"location":"reference/jvm/profile-tools/#visualvm","title":"VisualVM","text":"<p>VisualVM provides a simplified and robust profiling tool for Java applications, bundled with the Java Development Kit (JDK) and using JConsole, jstat, jstack, jinfo, and jmap.</p> <p></p> UbuntuMacOSX <p>Ubuntu / Debian includes VisualVM in the software center <pre><code>sudo apt install visualvm\n</code></pre></p> <p>Download the macOS application bundle and double-click to install.</p>"},{"location":"reference/jvm/profile-tools/#jdk-flight-recorder","title":"JDK Flight Recorder","text":"<p>JDK Flight Recorder is a production time profiling and diagnostics engine built into the JVM</p> <ul> <li>Extremely low overhead - no measurable impact on the running application</li> <li>High performance flight recording engine and high performance data collection</li> <li>Safe and reliable in production, tested on all platforms as part of the JVM/JDK-testing</li> <li>Time machine records data before, up to, and right after a problem occurs (even if the JVM process crashes)</li> </ul> <p><code>jcmd</code> to access the flight recorder data from the command line</p> <p>Mission control provides a graphical tool to visualise flight recorder data.</p> <ul> <li> Continuous Monitoring with JDK Flight Recorder</li> <li> JDK11 - Introduction to JDK Flight Recorder</li> <li> Production profiling with JDK Flight Recorder &amp; JDK Mission Control</li> </ul>"},{"location":"reference/jvm/profile-tools/#mission-control","title":"Mission Control","text":"<p>Mission Control is an open source desktop tool for visualising production time profiling and diagnostics from the JDK flight recorder tool. JDK Mission Control supports OpenJDK 11 and above.</p> <p>JDK Mission Control consists of</p> <ul> <li>A JDK Flight Recorder (JFR) analyser and visualiser</li> <li>A Java Management Extensions (JMX) Console</li> <li>A heap dump (hprof format) analyzer (JOverflow)</li> </ul> <p>Eclipse Mission Control from Adoptium</p> <p>Java Mission Control demo - 2014 outated but might be useful if nothing newer</p> <p> </p>"},{"location":"reference/jvm/profile-tools/#profiling-guides","title":"Profiling guides","text":"<p>Profiling your Java Application - A Beginner\u2019s Guide - Victor Rentea</p> <p>Explore three of the best free tools for profiling a Java (Spring) application:</p> <ul> <li>Using Java Flight Recorder to profile method execution times</li> <li>Using Micrometer-Prometheus-Grafana to profile connection starvation issues</li> <li>Using Glowroot to identify long-running queries</li> </ul> <p> </p>"},{"location":"reference/jvm/profile-tools/#references","title":"References","text":"<p>Java Profilers - Baeldung HotSpot Virtual Machine Garbage Collection Tuning Guide - Oracle</p>"},{"location":"reference/jvm/understanding-memory-usage/","title":"Memory usage","text":"<p>Adjusting the heap size and Garbage Collection behaviour is often the simplest means to improving application performance and stability. A mismatch between the heap size.</p> <p>Allocating additional memory to the HotSpot JVM is a relatively cheap way to improve the performance of an application.</p> <p>Garbage collection cost is in the form of execution pauses while the HotSpot JVM cleans up the no-longer-needed heap allocations.</p> <p>Report a full breakdown of the HotSpot JVM\u2019s memory usage upon exit using the following option combination:</p> <p>JVM Memory Usage Report</p> <p>```shell -XX:+UnlockDiagnosticVMOptions \u2011XX:NativeMemoryTracking=summary \u2011XX:+PrintNMTStatistics.</p> <p>```</p>"},{"location":"reference/jvm/understanding-memory-usage/#out-of-memory-errors","title":"Out Of Memory errors","text":"<p>When experiencing <code>OutOfMemory</code> errors, consider how the HotSpot JVM should behave if the application runs out of memory.</p> <p><code>-XX:+ExitOnOutOfMemoryError</code> - HotSpot JVM exits on the first OutOfMemory error, suitable if the JVM will be automatically restarted (such as in container services)</p> <p><code>-XX:+HeapDumpOnOutOfMemoryError</code> - dump contents of heap to file, <code>&lt;java_pid&gt;.hprof</code>, to help diagnose memory leaks</p> <p><code>-XX:HeapDumpPath</code> defines the path for the heap dump, default is current directory</p>"},{"location":"reference/jvm/understanding-memory-usage/#choose-a-garbage-collector","title":"Choose A Garbage Collector","text":"<p>The HotSpot Virtual Machine Garbage Collection Tuning Guide provides advice on selecting a suitable garbage collector (GC)</p> <p>G1GC collector is the default used by the JDK ergonomics process on most hardware.</p> <p>Other garbage collectors available include:</p> <p><code>-XX:+UseSerialGC</code> - serial collector, performing all GC work on a single thread</p> <p><code>-XX:+UseParallelGC</code> - parallel (throughput) collector, performs compaction using multiple threads.</p> <p><code>-XX:+UseZGC</code> - ZGC collector scalable low latency garbage collector (experimental in JDK 11, so requires <code>-XX:+UnlockExperimentalVMOptions</code>).</p> <p>Enable garbage collection logging</p> <p><code>-Xlog:gc</code> - basic GC logging</p> <p><code>-Xlog:gc*</code> - verbose GC logging</p>"},{"location":"reference/jvm/understanding-memory-usage/#object-allocation","title":"Object Allocation","text":"<p>Applications that create short-lived objects at a high allocation rates can lead to the premature promotion of short-lived objects to the old-generation heap space. There the objects will accumulate until a full garbage collection is needed</p> <p>To avoid premature promotion:</p> <p><code>-XX:NewSize=n</code> - initial size for the young generation</p> <p><code>-XX:MaxNewSize=n</code> - maximum size for the young generation</p> <p><code>-XX:MaxTenuringThreshold=n</code> - maximum number of young-generation collections an object can survive before it is promoted to the old generation</p>"},{"location":"reference/jvm/understanding-memory-usage/#just-in-time-optimisation","title":"Just In Time Optimisation","text":"<p>Understand how the Just In Time (JIT) compiler optimises the code.</p> <p>Once an application garbage collection pauses are an acceptable level, check the JIT compilers are optimizing the parts of your program you think are important for performance.</p> <p>Enable compilation logging:</p> <p><code>-XX:+PrintCompilation</code> print basic information about each JIT compilation to the console</p> <p><code>-XX:+UnlockDiagnosticVMOptions \u2011XX:+PrintCompilation \u2011XX:+PrintInlining</code> - information about method in-lining</p>"},{"location":"reference/performance/","title":"Clojure Performance","text":"<p>Two excellent presentations on Clojure performance</p>"},{"location":"reference/performance/#optimising-the-critical-path","title":"Optimising the critical path","text":"<p>Using two of Clojure's fundamental building blocks, macros and higher order functions, Clojure code can be sped up significantly without sacrificing common idioms.</p> <p>Premature optimisation is the root of all evil, this is not a reason to pass up opportunities to improve the critical 3%.</p> <p> </p>"},{"location":"reference/performance/#naked-performance","title":"Naked Performance","text":"<p>Lessons learned on building Clojure/Script systems that are both ridiculously fast and will fail fast on errors.</p> <p>Compare the performance of mutable, persistent &amp; zero-copy data structures, showing how to use interpreters and compilers to build beautiful and performant abstractions.</p> <p>A shot demo on building a simple non-blocking web server that runs idiomatic Clojure to serve millions of requests per second.</p> <p> </p>"},{"location":"reference/performance/#advanced-types","title":"Advanced types","text":"<p>Clojure support for Java Primitives</p> <p>Clojure has support for high-performance with Java primitive types in local contexts. All Java primitive types are supported: int, float, long, double, boolean, char, short, and byte.  In the extremely rare occasions where this is needed, it is added via metadata and therefore only adds to the existing code without rewriting it.</p> <p>Rather than write this Java:</p> <pre><code>static public float asum(float[] xs){\n  float ret = 0;\n  for(int i = 0; i &lt; xs.length; i++)\n    ret += xs[i];\n  return ret;\n}\n</code></pre> <p>you can write this Clojure:</p> <pre><code>(defn asum [^floats xs]\n  (areduce xs i ret (float 0)\n    (+ ret (aget xs i))))\n</code></pre> <p>and the resulting code is exactly the same speed (when run with java -server).</p>"},{"location":"reference/performance/#optimization-tips-for-types","title":"Optimization tips for types","text":"<p>All arguments are passed to Clojure fns as objects, so there's no point to putting non-array primitive type hints on fn args. Instead, use the let technique shown to place args in primitive locals if they need to participate in primitive arithmetic in the body.    (let [foo (int bar)] ...) is the correct way to get a primitive local. Do not use ^Integer etc.</p> <p>Don't rush to unchecked math unless you want truncating operations. HotSpot does a good job at optimizing the overflow check, which will yield an exception instead of silent truncation. On a typical example, that has about a 5% difference in speed - well worth it. Also, people reading your code don't know if you are using unchecked for truncation or performance - best to reserve it for the former and comment if the latter.</p> <p>There's usually no point in trying to optimize an outer loop, in fact it can hurt you as you'll be representing things as primitives which just have to be re-boxed in order to become args to the inner call. The only exception is reflection warnings - you must get rid of them in any code that gets called frequently.</p> <p>Almost every time someone presents something they are trying to optimize with hints, the faster version has far fewer hints than the original. If a hint doesn't improve things in the end - take it out.</p> <p>Many people seem to presume only the unchecked- ops do primitive arithmetic - not so. When the args are primitive locals, regular + and * etc do primitive math with an overflow check - fast and safe.</p> <p>So, the simplest route to fast math is to leave the operators alone and just make sure the source literals and locals are primitive. Arithmetic on primitives yields primitives. If you've got a loop (which you probably do if you need to optimize) make sure the loop locals are primitives first - then if you accidentally are producing a boxed intermediate result you'll get an error on recur. Don't solve that error by coercing your intermediate result, instead, figure out what argument or local is not primitive.</p>"},{"location":"reference/standard-library/","title":"Clojure Standard Library","text":"<p>Examples of using the functions from the <code>clojure.core</code> namespace and other important functions, macros and special forms that are part of the <code>org.clojure/clojure</code> library.</p> <p>There are approximately 700 functions and macros available in the <code>clojure.core</code> namespace.  These are referred to as the Clojure Standard Library.</p> <p>Counting functions in <code>clojure.core</code></p> <p>To get an accurate number of functions, call the <code>ns-publics</code> function with a namespace name <pre><code>(count (ns-publics 'clojure.core))\n</code></pre> Random Function is a simple project that prints out a random function from the given namespace, or from clojure.core by default.</p>"},{"location":"reference/standard-library/#functions-macros-and-special-forms","title":"Functions, Macros and Special forms","text":"<p>The majority of times macros and special forms act just like any other defined function (i.e. <code>fn</code>, <code>defn</code>)</p> <p>A macro is a piece of code that evaluates into a function when read by the macro reader, or by the developer using <code>macroexpand</code> function.  An expanded macro may also contain macros, so expansion could take place several levels (<code>macroexpand-all</code>).</p> <p>macros are not composable like functions, so functions like <code>apply</code> <code>reduce</code> <code>map</code> cannot use a macro (use a function instead).</p> <p>Special forms are built into the Clojure runtime, so will not be found in clojure.core</p> <ul> <li>Special forms: <code>if</code> <code>do</code> <code>let</code> <code>quote</code> <code>var</code> <code>fn</code> <code>loop</code> <code>recur</code> <code>throw</code> <code>try</code></li> <li>Special forms for Java interop:  <code>.</code> <code>new</code> <code>set!</code></li> </ul>"},{"location":"reference/standard-library/collections/","title":"Standard Library: Collections","text":"<p>Functions to create and work with the Clojure collection types, mainly maps, vectors and sets</p> <p>See Sequences for functions around lists and (lazy) sequences</p>"},{"location":"reference/standard-library/cond-thread-macro/","title":"Clojure cond-&gt;","text":"<p><code>cond-&gt;</code> and <code>cond-&gt;&gt;</code> are versatile macros available since version 1.5, although its more of a nieche use, its really useful in that neiche</p> <p>Usage: (cond-&gt; expr &amp; clauses)</p> <p>Takes an expression and a set of test/form pairs.</p> <p>Threads expr (via -&gt;) through each form for which the corresponding test expression is true.</p> <p>Note that, unlike cond branching, cond-&gt; threading does not short circuit after the first true test expression.</p>"},{"location":"reference/standard-library/cond-thread-macro/#deconstruct","title":"Deconstruct","text":"<pre><code>(cond-&gt; 10\n  false inc)\n;; =&gt; 10\n</code></pre> <p>In the above example 10 is the expr mentioned in the docstring and everything after it are the clauses.</p> <p>Each clause is a pair made up of a test and a form.  There is a single clause with the value false as the test the function inc as the form.</p> <p>Since the test evaluates to a false value the expression is not threaded into the form. As a result the original expression, 10, is returned.</p> <p>Let\u2019s look at an example with a truthy test.</p> <pre><code>(cond-&gt; 10\n  true (- 2)\n;;=&gt; 8\n</code></pre> <p>Once again, 10 is the starting expression. The single clause has a test that evaluates to true so the expression is threaded into the first position of the form (- 2). The result is 8 and this is returned.</p> <p>An example of a <code>cond-&gt;</code> with multiple clauses. Explanations are inline with the code.</p> <pre><code>(cond-&gt; 10 ; start with 10\n  ;; test evaluates to true, so apply inc to 10. Current value is now 11.\n  true inc\n\n  ;; (zero? 1) evaluates to false, do not perform action. Current value stays 11.\n  (zero? 1) (+ 2)\n\n  ;; (pos? 4) evaluates to true, thread 11 into first position of form.\n  (pos? 4) (- 5))\n;; =&gt; 6 ; The result of (- 11 5) is 6.\n</code></pre> <p>If you understand the above example then you have a good grasp of cond-&gt;. But when is this functionality useful?</p>"},{"location":"reference/standard-library/cond-thread-macro/#when-to-use-cond-","title":"When to use cond-&gt;?","text":"<p>Looking through the codebases I work on, I almost primarily see cond-&gt; being used with the initial expression being a hash-map. It is being used in situations where we want to selectively assoc, update, or dissoc something from a map.</p> <p>If cond-&gt; did not exist you would accomplish those selective modifications with code similar to below.</p> <pre><code>(if (some-pred? q)\n  (assoc m :a-key :a-value)\n  m)\n</code></pre> <p>Rewrite the above with cond-&gt;.</p> <pre><code>(cond-&gt; m\n  (some-pred? q) (assoc :a-key :a-value))\n</code></pre> <p>If you\u2019re not used to seeing cond-&gt; the above transformation might seem like a step backwards. I know it felt that way to me when I first saw cond-&gt;. Give yourself time to get familiar with it and you\u2019ll be glad you\u2019re using it.</p> <p>A meatier example of using cond-&gt; is demonstrated below. Here we\u2019re manipulating data structures designed for use with honeysql to generate SQL statements. We start with a base-query and selectively modify it based on incoming parameters.</p> <pre><code>(defn query [req-params]\n  (let [and-clause (fnil conj [:and])\n        base-query {:select [:name :job]\n                    :from [:person]}]\n    (cond-&gt; base-query\n      (:job req-params) (update :where and-clause [:= :job (:job req-params)])\n      (:name req-params) (update :where and-clause [:= :name (:name req-params)])\n      (:min-age req-params) (update :where and-clause [:&gt; :age (:min-age req-params)]))))\n</code></pre> <p>Hopefully this gives you a taste of cond-&gt;. I\u2019ve found it to be quite useful. It has a place in every Clojure developer\u2019s toolbox.</p>"},{"location":"reference/standard-library/destructuring/","title":"Destructuring","text":"<p>Destructuring is a form of pattern matching where you return specific elements from a collection and assign those elements names.  It is commonly used in function parameter lists or with the <code>let</code> function.</p> <p>Destructuring is also known as abstract structural binding</p> <p>A simple example of destructuring is assigning the values of a collection, in this case a vector.</p> <pre><code>(def co-ordinates [5 7])\n\n(let [[x y] co-ordinates]\n (str \"x:\" x \"y:\" y))\n;; =&gt; x: 5 y: 7\n</code></pre> <p>;; Sometimes we do not need all the information, so we can just use the elements we need.</p> <pre><code>(def three-dee-co-ordinates [2 7 4])\n\n(let [[x y] three-dee-co-ordinates]\n  (str \"I only need the 2D co-ordinates, X: \" x \" and Y: \" y ))\n;; =&gt; \"I only need the 2D co-ordinates, X: 2 and Y: 7\"\n</code></pre> <p>Its quite common to take the first element as a specific name and use another name for the rest of the elements</p> <pre><code>(def shopping-list [\"oranges\" \"apples\" \"spinach\" \"carrots\" \"potatoes\" \"beetroot\"])\n\n(defn get-item [items]\n  (let [[next-item &amp; other-items] items]\n    (str \"The next item to get is: \" next-item)))\n\n(get-item shopping-list)\n;; =&gt; \"The next item to get is: oranges\"\n</code></pre> <p>This example seems a little redundant at first, however if we add recursion then we can iterate through the shopping list and it should make more sense</p> <p>splitting a vector into a head and a tail. When defining a function with an arglist** you use an ampersand. The same is true in destructuring.</p> <pre><code>(def indexes [1 2 3])\n\n(let [[x &amp; more] indexes]\n         (println \"x:\" x \"more:\" more))\n;; =&gt; x: 1 more: (2 3)\n</code></pre> <p>It's also worth noting that you can bind the entire vector to a local using the :as directive.</p> <pre><code>(def indexes [1 2 3])\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userindexes","title":"'user/indexes","text":"<pre><code> (let [[x &amp; more :as full-list] indexes]\n         (println \"x:\" x \"more:\" more \"full list:\" full-list))\n;; =&gt; x: 1 more: (2 3) full list: [1 2 3]\n</code></pre> <p>Vector examples are the easiest; however, in practice I find myself using destructuring with maps far more often.</p> <p>Simple destructuring on a map is as easy as choosing a local name and providing the key.</p> <pre><code>(def point {:x 5 :y 7})\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userpoint","title":"'user/point","text":"<pre><code> (let [{the-x :x the-y :y} point]\n         (println \"x:\" the-x \"y:\" the-y))\n;; =&gt; x: 5 y: 7\n</code></pre> <p>As the example shows, the values of :x and :y are bound to locals with the names the-x and the-y. In practice we would never prepend \"the-\" to our local names; however, using different names provides a bit of clarity for our first example. In production code you would be much more likely to want locals with the same name as the key. This works perfectly well, as the next example shows.</p> <pre><code>(def point {:x 5 :y 7})\n</code></pre>"},{"location":"reference/standard-library/destructuring/#userpoint_1","title":"'user/point","text":"<p>user=&gt; (let [{x :x y :y} point]          (println \"x:\" x \"y:\" y)) x: 5 y: 7</p> <p>While this works perfectly well, creating locals with the same name as the keys becomes tedious and annoying (especially when your keys are longer than one letter). Clojure anticipates this frustration and provides :keys directive that allows you to specify keys that you would like as locals with the same name.</p> <p>user=&gt; (def point {:x 5 :y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_2","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y]} point]          (println \"x:\" x \"y:\" y)) x: 5 y: 7</p> <p>There are a few directives that work while destructuring maps. The above example shows the use of :keys. In practice I end up using :keys the most; however, I've also used the :as directive while working with maps.</p> <p>The following example illustrates the use of an :as directive to bind a local with the entire map.</p> <p>user=&gt; (def point {:x 5 :y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_3","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y] :as the-point} point]          (println \"x:\" x \"y:\" y \"point:\" the-point)) x: 5 y: 7 point: {:x 5, :y 7}</p> <p>We've now seen the :as directive used for both vectors and maps. In both cases the local is always assigned to the entire expression that is being destructured.</p> <p>For completeness I'll document the :or directive; however, I must admit that I've never used it in practice. The :or directive is used to assign default values when the map being destructured doesn't contain a specified key.</p> <p>user=&gt; (def point {:y 7})</p>"},{"location":"reference/standard-library/destructuring/#userpoint_4","title":"'user/point","text":"<p>user=&gt; (let [{:keys [x y] :or {x 0 y 0}} point]          (println \"x:\" x \"y:\" y)) x: 0 y: 7</p> <p>Lastly, it's also worth noting that you can destructure nested maps, vectors and a combination of both.</p> <p>The following example destructures a nested map</p> <p>user=&gt; (def book {:name \"SICP\" :details {:pages 657 :isbn-10 \"0262011530\"}})</p>"},{"location":"reference/standard-library/destructuring/#userbook","title":"'user/book","text":"<p>user=&gt; (let [{name :name {pages :pages isbn-10 :isbn-10} :details} book]          (println \"name:\" name \"pages:\" pages \"isbn-10:\" isbn-10)) name: SICP pages: 657 isbn-10: 0262011530</p> <p>As you would expect, you can also use directives while destructuring nested maps.</p> <p>user=&gt; (def book {:name \"SICP\" :details {:pages 657 :isbn-10 \"0262011530\"}})</p>"},{"location":"reference/standard-library/destructuring/#userbook_1","title":"'user/book","text":"<p>user=&gt; user=&gt; (let [{name :name {:keys [pages isbn-10]} :details} book]          (println \"name:\" name \"pages:\" pages \"isbn-10:\" isbn-10)) name: SICP pages: 657 isbn-10: 0262011530</p> <p>Destructuring nested vectors is also very straight-forward, as the following example illustrates</p> <p>user=&gt; (def numbers [[1 2][3 4]])</p>"},{"location":"reference/standard-library/destructuring/#usernumbers","title":"'user/numbers","text":"<p>user=&gt; (let [[[a b][c d]] numbers]   (println \"a:\" a \"b:\" b \"c:\" c \"d:\" d)) a: 1 b: 2 c: 3 d: 4</p> <pre><code>Since binding forms can be nested within one another arbitrarily, you can pull apart just about anything -- http://clojure.org/special_forms\n</code></pre> <p>The following example destructures a map and a vector at the same time.</p> <p>user=&gt; (def golfer {:name \"Jim\" :scores [3 5 4 5]})</p>"},{"location":"reference/standard-library/destructuring/#usergolfer","title":"'user/golfer","text":"<p>user=&gt; (let [{name :name [hole1 hole2] :scores} golfer]          (println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2)) name: Jim hole1: 3 hole2: 5</p> <p>The same example can be rewritten using a function definition to show the simplicity of using destructuring in parameter lists.</p> <p>user=&gt; (defn print-status [{name :name [hole1 hole2] :scores}]   (println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))</p>"},{"location":"reference/standard-library/destructuring/#userprint-status","title":"'user/print-status","text":"<p>user=&gt; (print-status {:name \"Jim\" :scores [3 5 4 5]}) name: Jim hole1: 3 hole2: 5</p> <p>There are other (less used) directives and deeper explanations available on http://clojure.org/special_forms and in The Joy of Clojure. I recommend both.</p> <p>**(defn do-something [x y &amp; more] ... ) Posted by Jay Fields at 7:44 AM Email ThisBlogThis!Share to TwitterShare to FacebookShare to Pinterest Labels: clojure, destructuring 10 comments:</p> <pre><code>fogus8:26 AM\n\nNice post. One other note that naturally follows from the end of your post is that destructuring forms the basis of Clojure's named arguments:\n\n(defn print-status [&amp; {name :name [hole1 hole2] :scores}]\n(println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))\n\n(print-status :name \"Joey\" :scores [42 18])\n\n\nYou can also use pre-conditions to check if certain arguments are passed in:\n\n\n(defn print-status [&amp; {name :name [hole1 hole2] :scores}]\n{:pre [name]}\n(println \"name:\" name \"hole1:\" hole1 \"hole2:\" hole2))\n\n(print-status :scores [42 18])\n; java.lang.AssertionError: Assert failed: name\n\n(print-status :name \"Joey\" :scores [42 18])\n; name: Joey hole1: 42 hole2: 18\n\n\n:f\nReply\nJay Fields9:08 AM\n\nGood stuff Fogus, thanks.\n\nCheers, Jay\nReply\nMatt Todd5:31 PM\n\nCan you combine :as and :or et al?\nReply\nAnonymous7:29 PM\n\nYes, all the directives can be used at the same time.\n\nCheers, Jay\nReply\nLaurent PETIT3:08 AM\n</code></pre> <p>Hi, one note about using destructuring for function arguments : by doing so, you're quite explicitly establishing a more detailed contract with the consumer of the function. That is, you open the internals of the passed arguments.</p> <p>Depending on the fact that the user may or may not be aware of the internals of the arguments, it may or may not be a good idea.</p> <p>So I tend to think about the use of destructuring function arguments directly in the function signature, depending on whether the \"layout\" of the arguments of the function is part of the user API.     Reply</p>"},{"location":"reference/standard-library/destructuring/#clojure-destructuring-tutorial-and-cheat-sheet","title":"Clojure Destructuring Tutorial and Cheat Sheet","text":"<p>(Related blog post)</p> <p>Simply put, destructuring in Clojure is a way extract values from a data structure and bind them to symbols, without having to explicitly traverse the data structure. It allows for elegant and concise Clojure code.</p>"},{"location":"reference/standard-library/destructuring/#vectors","title":"Vectors","text":"<p>Syntax: <code>[symbol another-symbol] [\"value\" \"another-value\"]</code></p> <pre><code>(def my-vector [:a :b :c :d])\n(def my-nested-vector [:a :b :c :d [:x :y :z]])\n\n(let [[a b c d] my-vector]\n  (println a b c d))\n;; =&gt; :a :b :c :d\n\n(let [[a _ _ d [x y z]] my-nested-vector]\n  (println a d x y z))\n;; =&gt; :a :d :x :y :z\n</code></pre> <p>You don't have to match the full vector.</p> <pre><code>(let [[a b c] my-vector]\n  (println a b c))\n;; =&gt; :a :b :c\n</code></pre> <p>You can use <code>&amp; the-rest</code> to bind the remaining part of the vector to <code>the-rest</code>.</p> <pre><code>(let [[a b &amp; the-rest] my-vector]\n  (println a b the-rest))\n;; =&gt; :a :b (:c :d)\n</code></pre> <p>When a destructuring form \"exceeds\" a vector (i.e. there not enough items in the vector to bind to), the excess symbols will be bound to <code>nil</code>.</p> <pre><code>(let [[a b c d e f g] my-vector]\n  (println a b c d e f g))\n;; =&gt; :a :b :c :d nil nil nil\n</code></pre> <p>You can use <code>:as some-symbol</code> as the last two items in the destructuring form to bind the whole vector to <code>some-symbol</code></p> <pre><code>(let [[:as all] my-vector]\n  (println all))\n;; =&gt; [:a :b :c :d]\n\n(let [[a :as all] my-vector]\n  (println a all))\n;; =&gt; :a [:a :b :c :d]\n\n(let [[a _ _ _ [x y z :as nested] :as all] my-nested-vector]\n  (println a x y z nested all))\n;; =&gt; :a :x :y :z [:x :y :z] [:a :b :c :d [:x :y :z]]\n</code></pre> <p>You can use both <code>&amp; the-rest</code> and <code>:as some-symbol</code>.</p> <pre><code>(let [[a b &amp; the-rest :as all] my-vector]\n  (println a b the-rest all))\n;; =&gt; :a :b (:c :d) [:a :b :c :d]\n</code></pre>"},{"location":"reference/standard-library/destructuring/#optional-arguments-for-functions","title":"Optional arguments for functions","text":"<p>With destructuring and the <code>&amp; the-rest</code> form, you can specify optional arguments to functions.</p> <pre><code>(defn foo [a b &amp; more-args]\n  (println a b more-args))\n(foo :a :b) ;; =&gt; :a :b nil\n(foo :a :b :x) ;; =&gt; :a :b (:x)\n(foo :a :b :x :y :z) ;; =&gt; :a :b (:x :y :z)\n\n(defn foo [a b &amp; [x y z]]\n  (println a b x y z))\n(foo :a :b) ;; =&gt; :a :b nil nil nil\n(foo :a :b :x) ;; =&gt; :a :b :x nil nil\n(foo :a :b :x :y :z) ;; =&gt; :a :b :x :y :z\n</code></pre>"},{"location":"reference/standard-library/destructuring/#maps","title":"Maps","text":"<p>Syntax: <code>{symbol :key, another-symbol :another-key} {:key \"value\" :another-key \"another-value\"}</code></p> <pre><code>(def my-hashmap {:a \"A\" :b \"B\" :c \"C\" :d \"D\"})\n(def my-nested-hashmap {:a \"A\" :b \"B\" :c \"C\" :d \"D\" :q {:x \"X\" :y \"Y\" :z \"Z\"}})\n\n(let [{a :a d :d} my-hashmap]\n  (println a d))\n;; =&gt; A D\n\n(let [{a :a, b :b, {x :x, y :y} :q} my-nested-hashmap]\n  (println a b x y))\n;; =&gt; A B X Y\n</code></pre> <p>Similar to vectors, if a key is not found in the map, the symbol will be bound to <code>nil</code>.</p> <pre><code>(let [{a :a, not-found :not-found, b :b} my-hashmap]\n  (println a not-found b))\n;; =&gt; A nil B\n</code></pre> <p>You can provide an optional default value for these missing keys with the <code>:or</code> keyword and a map of default values.</p> <pre><code>(let [{a :a, not-found :not-found, b :b, :or {not-found \":)\"}} my-hashmap]\n  (println a not-found b))\n;; =&gt; A :) B\n</code></pre> <p>The <code>:as some-symbol</code> form is also available for maps, but unlike vectors it can be specified anywhere (but still preferred to be the last two pairs).</p> <pre><code>(let [{a :a, b :b, :as all} my-hashmap]\n  (println a b all))\n;; =&gt; A B {:a A :b B :c C :d D}\n</code></pre> <p>And combining <code>:as</code> and <code>:or</code> keywords (again, <code>:as</code> preferred to be the last).</p> <pre><code>(let [{a :a, b :b, not-found :not-found, :or {not-found \":)\"}, :as all} my-hashmap]\n  (println a b not-found all))\n;; =&gt; A B :) {:a A :b B :c C :d D}\n</code></pre> <p>There is no <code>&amp; the-rest</code> for maps.</p>"},{"location":"reference/standard-library/destructuring/#shortcuts","title":"Shortcuts","text":"<p>Having to specify <code>{symbol :symbol}</code> for each key is repetitive and verbose (it's almost always going to be the symbol equivalent of the key), so shortcuts are provided so you only have to type the symbol once.</p> <p>Here are all the previous examples using the <code>:keys</code> keyword followed by a vector of symbols:</p> <pre><code>(let [{:keys [a d]} my-hashmap]\n  (println a d))\n;; =&gt; A D\n\n(let [{:keys [a b], {:keys [x y]} :q} my-nested-hashmap]\n  (println a b x y))\n;; =&gt; A B X Y\n\n(let [{:keys [a not-found b]} my-hashmap]\n  (println a not-found b))\n;; =&gt; A nil B\n\n(let [{:keys [a not-found b], :or {not-found \":)\"}} my-hashmap]\n  (println a not-found b))\n;; =&gt; A :) B\n\n(let [{:keys [a b], :as all} my-hashmap]\n  (println a b all))\n;; =&gt; A B {:a A :b B :c C :d D}\n\n(let [{:keys [a b not-found], :or {not-found \":)\"}, :as all} my-hashmap]\n  (println a b not-found all))\n;; =&gt; A B :) {:a A :b B :c C :d D}\n</code></pre> <p>There are also <code>:strs</code> and <code>:syms</code> alternatives, for when your map has strings or symbols for keys (instead of keywords), respectively.</p> <pre><code>(let [{:strs [a d]} {\"a\" \"A\", \"b\" \"B\", \"c\" \"C\", \"d\" \"D\"}]\n  (println a d))\n;; =&gt; A D\n\n(let [{:syms [a d]} {'a \"A\", 'b \"B\", 'c \"C\", 'd \"D\"}]\n  (println a d))\n;; =&gt; A D\n</code></pre>"},{"location":"reference/standard-library/destructuring/#keyword-arguments-for-function","title":"Keyword arguments for function","text":"<p>Map destructuring also works with lists (but not vectors).</p> <pre><code>(let [{:keys [a b]} '(\"X\", \"Y\", :a \"A\", :b \"B\")]\n(println a b))\n;; =&gt; A B\n</code></pre> <p>This allows your functions to have optional keyword arguments.</p> <pre><code>(defn foo [a b &amp; {:keys [x y]}]\n  (println a b x y))\n(foo \"A\" \"B\")  ;; =&gt; A B nil nil\n(foo \"A\" \"B\" :x \"X\")  ;; =&gt; A B X nil\n(foo \"A\" \"B\" :x \"X\" :y \"Y\")  ;; =&gt; A B X Y\n</code></pre>"},{"location":"reference/standard-library/predicate-functions/","title":"Clojure Predicate functions","text":"<p>A predicate function takes a single argument and returns a truthy value, e.g. <code>true</code> or <code>false</code></p> <p></p> <p>There are over 70 predicate functions provided by the <code>clojure.core</code> namespace. </p> <code>clojure.core</code> predicates Description &gt;0? (^:private) &gt;1? (^:private) any? associative? boolean? bound? bytes? chunked-seq? (^:static) class? coll? contains? counted? decimal? delay? distinct? double? empty? even? every? false? fits-table? (defn-) float? fn? future? future-cancelled? future-done? ident? identical? ifn? indexed? inst? int? integer? isa? is-annotation? (defn-) is-runtime-annotation? (defn-) keyword? libspec? (defn-) list? map-entry? nat-int? neg? neg-int? nil? number? odd? pos? pos-int? qualified-ident? qualified-keyword? qualified-symbol? ratio? rational? reader-conditional? realized? reduced? reversible? seqable? sequential? set? simple-ident? simple-keyword? simple-symbol? some? sorted? special-symbol? symbol? tagged-literal? thread-bound? true? uri? uuid? var? volatile? zero?"},{"location":"reference/standard-library/sequences/","title":"Standard Library: Sequences","text":"<p>Functions to create and work with the Clojure sequences, including lists and sequence generators</p>"},{"location":"reference/standard-library/sequences/#sequence-access","title":"Sequence access","text":"Function Description <code>first</code> <code>second</code> <code>rest</code> <code>last</code> <code>butlast</code> <code>nth</code>"},{"location":"reference/standard-library/sequences/#infinite-sequence-generators","title":"Infinite sequence generators","text":"Function Description <code>range</code> <code>cycle</code> <code>iterate</code>"},{"location":"reference/standard-library/regular-expressions/","title":"Regular Expressions - regex","text":"<p>Regular expressions are a powerful and compact way to find specific patterns in text strings. Clojure provides a simple syntax for Java regex patterns.</p> <p><code>#\"pattern\"</code> is the literal representation of a regular expressions in Clojure, where <code>pattern</code> is the regular expression.</p> <p>Create regular expression pattern</p> <p><code>(re-pattern pattern)</code> will return the Clojure literal representation of a given regex pattern.</p> <p>A string can become a regular expression pattern, e.g. <code>\":\"</code> becomes the regex pattern <code>#\":\"</code> <pre><code>(re-pattern \":\")\n</code></pre></p> <p>The regular expression syntax cheatsheet by Mozilla is an excellent reference for regular expression patterns.</p>"},{"location":"reference/standard-library/regular-expressions/#regular-expressions-overview","title":"Regular expressions overview","text":"<p>Regular expressions in Clojure</p> <p> </p> <p>Find the most common word in a book using regular expressions</p> <p> </p> Double escaping not required <p>The Clojure syntax means you do not need to double escape special characters, eg. <code>\\\\</code>, and keeps the patterns clean and simple to read. In other languages, backslashes intended for consumption by the regex compiler must be doubled.</p> <pre><code>(java.util.regex.Pattern/compile \"\\\\d\")\n;;=&gt; #\"\\d\"\n</code></pre> <p>The rules for embedding unusual literal characters or predefined character classes are listed in the Javadoc for Pattern.</p>"},{"location":"reference/standard-library/regular-expressions/#host-platform-support","title":"Host platform support","text":"<p>Clojure runs on the Java Virtual Machine and uses Java regular expressions.</p> <p>Regular expressions in Clojure create a java.util.regex.Pattern type</p> <pre><code>(type #\"pattern\")\n;;=&gt; java.util.regex.Pattern\n</code></pre> <p>ClojureScript runs on JavaScript engines and uses Javascript regular expressions.</p>"},{"location":"reference/standard-library/regular-expressions/#option-flags","title":"Option flags","text":"<p>Regular expression option flags can make a pattern case-insensitive or enable multiline mode. Clojure's regex literals starting with (?) set the mode for the rest of the pattern. For example, the pattern <code>#\"(?i)yo\"</code> matches the strings <code>\u201cyo\u201d</code>, <code>\u201cyO\u201d</code>, <code>\u201cYo\u201d</code>, and <code>\u201cYO\u201d</code>. <p>Flags that can be used in Clojure regular-expression patterns, along with their long name and a description of what they do. See Java's documentation for the java.util.regex.Pattern class for more details.</p> Flag Flag Name Description d UNIX_LINES ., ^, and $ match only the Unix line terminator '\\n'. i CASE_INSENSITIVE ASCII characters are matched without regard to uppercase or lower-case. x COMMENTS Whitespace and comments in the pattern are ignored. m MULTILINE ^ and $ match near line terminators instead of only at the beginning or end of the entire input string. s DOTALL . matches any character including the line terminator. u UNICODE_CASE Causes the i flag to use Unicode case insensitivity instead of ASCII. <p>The re-seq function is Clojure's regex workhorse. It returns a lazy seq of all matches in a string, which means it can be used to efficiently test whether a string matches or to find all matches in a string or a mapped file:</p> <pre><code>(re-seq #\"\\w+\" \"one-two/three\")\n;;=&gt; (\"one\" \"two\" \"three\")\n</code></pre> <p>The preceding regular expression has no capturing groups, so each match in the returned seq is a string. A capturing group (subsegments that are accessible via the returned match object) in the regex causes each returned item to be a vector:</p> <pre><code>(re-seq #\"\\w*(\\w)\" \"one-two/three\")\n([\"one\" \"e\"] [\"two\" \"o\"] [\"three\" \"e\"])\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/#references","title":"References","text":"<p>4Clojure #37 - regular expressions Regex in Clojure - purelyfunctional.tv</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/","title":"Common Regular Expression patterns","text":"<p>Common string formats used in software development and examples of regular expressions to check their correctness.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#username-regular-expression-pattern","title":"Username Regular Expression Pattern","text":"<p>A 8 to 24 character passwords that can include any lower case character or digit (number).  Only the underscore and dash special characters can be used.</p> <pre><code>(re-matches #\"^[a-z0-9_-]{8,24}$\" \"good-username\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^[a-z0-9_-]{8,24}$\n\n^                    # Start of the line\n  [a-z0-9_-]         # Match characters and symbols in the list, a-z, 0-9 , underscore , hyphen\n             {8,24}  # Length at least 8 characters and maximum length of 24\n$                    # End of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#password-regular-expression-pattern","title":"Password Regular Expression Pattern","text":"<p>A password should be 8 to 24 character string with at least one digit, one upper case letter, one lower case letter and one special symbol, <code>@#$%</code>.</p> <pre><code>(re-matches #\"((?=.*\\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%]).{8,24})\" \"G00d @ username\")\n</code></pre> <p>The order of the grouping formulas does not matter</p> <p>Breakdown the regex pattern:</p> <pre><code>((?=.*\\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%]).{8,24})\n\n(   # Start of group\n  (?=.*\\d)  #   must contains one digit from 0-9\n  (?=.*[a-z])  #   must contains one lowercase characters\n  (?=.*[A-Z])  #   must contains one uppercase characters\n  (?=.*[@#$%])  #   must contains one special symbols in the list \"@#$%\"\n              .  #     match anything with previous condition checking\n                {8,24} #        length at least 8 characters and maximum of 24\n)   # End of group\n</code></pre> <p><code>?=</code> means apply the assertion condition, which is meaningless by itself and works in combination with others.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hexadecimal-color-code-regular-expression-pattern","title":"Hexadecimal Color Code Regular Expression Pattern","text":"<p>The string must start with a <code>#</code>symbol , follow by a letter from <code>a</code> to <code>f</code>, <code>A</code> to <code>Z</code> or a digit from <code>0</code> to <code>9</code> with a length of exactly 3 or 6.` This regular expression pattern is very useful for the Hexadecimal web colors code checking.</p> <pre><code>(re-matches #\"^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$\" \"#FFAABB\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$\n\n^   #start of the line\n #   #  must contain a \"#\" symbols\n (   #  start of group #1\n  [A-Fa-f0-9]{3} #    any strings in the list, with length of 3\n  |   #    ..or\n  [A-Fa-f0-9]{6} #    any strings in the list, with length of 6\n )   #  end of group #1\n$   #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#email-regular-expression-pattern","title":"Email Regular Expression Pattern","text":"<p>The account side of an email address starts with <code>_A-Za-z0-9-\\\\+</code> optional follow by <code>.[_A-Za-z0-9-]</code>, ending with an <code>@</code> symbol.</p> <p>The  domain starts with <code>A-Za-z0-9-</code>, follow by first level domain, e.g <code>.org</code>, <code>.io</code> and <code>.[A-Za-z0-9]</code> optionally follow by a second level domain, e.g. <code>.ac.uk</code>, <code>.com.au</code> or  <code>\\\\.[A-Za-z]{2,}</code>, where second level domain must start with a dot <code>.</code> and length must equal or more than 2 characters.</p> <pre><code>(re-matches\n  #\"^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$\"\n  \"jenny.jenn@jetpack.com.au\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^[_A-Za-z0-9-]+(\\\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\\\\.[A-Za-z0-9]+)*(\\\\.[A-Za-z]{2,})$\n\n^   #start of the line\n  [_A-Za-z0-9-]+ #  must start with string in the bracket [ ], must contains one or more (+)\n  (   #  start of group #1\n    \\\\.[_A-Za-z0-9-]+ #     follow by a dot \".\" and string in the bracket [ ], must contains one or more (+)\n  )*   #  end of group #1, this group is optional (*)\n    @   #     must contains a \"@\" symbol\n     [A-Za-z0-9]+       #        follow by string in the bracket [ ], must contains one or more (+)\n      (   #    start of group #2 - first level TLD checking\n       \\\\.[A-Za-z0-9]+  #        follow by a dot \".\" and string in the bracket [ ], must contains one or more (+)\n      )*  #    end of group #2, this group is optional (*)\n      (   #    start of group #3 - second level TLD checking\n       \\\\.[A-Za-z]{2,}  #        follow by a dot \".\" and string in the bracket [ ], with minimum length of 2\n      )   #    end of group #3\n$   #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hintdouble-escaping-special-characters","title":"Hint::Double escaping special characters","text":"<p>Double escaping of special characters is not required in the Clojure syntax.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#image-file-name-and-extension-regular-expression-pattern","title":"Image File name and Extension Regular Expression Pattern","text":"<p>A file extension name is 1 or more characters without white space, follow by dot <code>.</code> and string end in <code>jpg</code> or <code>png</code> or <code>gif</code> or <code>bmp</code>.  The file name extension is case-insensitive.</p> <p>Change the combination <code>(jpg|png|gif|bmp)</code> for other file extension.</p> <pre><code>(re-matches #\"(?i)([^\\s]+(\\.(jpg|png|gif|bmp))$)\" \"clojure-logo.png\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>([^\\s]+(\\.(?i)(jpg|png|gif|bmp))$)\n\n(   #Start of the group #1\n [^\\s]+   #  must contains one or more anything (except white space)\n       (  #    start of the group #2\n         \\.  # follow by a dot \".\"\n         (?i)  # ignore the case sensitive checking\n             (  #   start of the group #3\n              jpg #       contains characters \"jpg\"\n              |  #       ..or\n              png #       contains characters \"png\"\n              |  #       ..or\n              gif #       contains characters \"gif\"\n              |  #       ..or\n              bmp #       contains characters \"bmp\"\n             )  #   end of the group #3\n       )  #     end of the group #2\n  $   #  end of the string\n)   #end of the group #1\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#hintin-line-modifiers-not-supported-in-javascript","title":"Hint::in-line modifiers not supported in JavaScript","text":"<p>The REPL above uses ClojureScript, hosted on JavaScript. JavaScript does not support in-line modifier flags such as <code>(?i)</code> for a case insensitive pattern.  In-line flags will be converted by the ClojureScript reader if they are the first element in the literal regular expression pattern, or if the <code>js/RegExp</code> function is used to create the regular expression.</p>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#ip-address-regular-expression-pattern","title":"IP Address Regular Expression Pattern","text":"<p>An IP address comprises of 4 groups of numbers between 0 and 255, with each group separated by a dot.</p> <p>Example IP address are: <code>192.168.0.1</code>, <code>127.0.0.1</code>, <code>192.120.240.100</code></p> <pre><code>(re-matches\n  #\"^([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])$\"\n  \"192.168.0.1\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>^([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.\n([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])\\\\.([01]?\\\\d\\\\d?|2[0-4]\\\\d|25[0-5])$\n\n^  #start of the line\n (  #  start of group #1\n   [01]?\\\\d\\\\d? #    Can be one or two digits. If three digits appear, it must start either 0 or 1\n        #    e.g ([0-9], [0-9][0-9],[0-1][0-9][0-9])\n    |  #    ...or\n   2[0-4]\\\\d #    start with 2, follow by 0-4 and end with any digit (2[0-4][0-9])\n    |           #    ...or\n   25[0-5]      #    start with 2, follow by 5 and end with 0-5 (25[0-5])\n )  #  end of group #2\n  \\.            #  follow by a dot \".\"\n....            # repeat with 3 time (3x)\n$  #end of the line\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#time-format-regular-expression-pattern","title":"Time Format Regular Expression Pattern","text":"<p>Time in 12-Hour Format Regular Expression Pattern.  The 12-hour clock format start between 0-12, then a semi colon, <code>:</code>, follow by <code>00-59</code>.  The pattern ends with <code>am</code> or <code>pm</code>.</p> <pre><code>(re-matches #\"(?i)(1[012]|[1-9]):[0-5][0-9](\\s)?(am|pm)\" \"12:59am\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>(1[012]|[1-9]):[0-5][0-9](\\\\s)?(?i)(am|pm)\n\n(    #start of group #1\n 1[012]    #  start with 10, 11, 12\n |    #  or\n [1-9]    #  start with 1,2,...9\n)    #end of group #1\n :    #    follow by a semi colon (:)\n  [0-5][0-9]   #   follow by 0..5 and 0..9, which means 00 to 59\n            (\\\\s)?  #        follow by a white space (optional)\n                  (?i)  #          next checking is case insensitive\n                      (am|pm) #            follow by am or pm\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#time-in-24-hour-format-regular-expression-pattern","title":"Time in 24-Hour Format Regular Expression Pattern","text":"<p>The 24-hour clock format start between 0-23 or 00-23, then a semi colon <code>:</code> and follow by 00-59.</p> <pre><code>(re-matches #\"(([01]?[0-9]|2[0-3]):[0-5][0-9])\" \"23:58\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>([01]?[0-9]|2[0-3]):[0-5][0-9]\n\n(    #start of group #1\n [01]?[0-9]   #  start with 0-9,1-9,00-09,10-19\n |    #  or\n 2[0-3]    #  start with 20-23\n)    #end of group #1\n :    #  follow by a semi colon (:)\n  [0-5][0-9]   #    follow by 0..5 and 0..9, which means 00 to 59\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#date-format-ddmmyyyy-regular-expression-pattern","title":"Date Format (dd/mm/yyyy) Regular Expression Pattern","text":"<p>Date format in the form <code>dd/mm/yyyy</code>. Validating a leap year and if there is 30 or 31 days in a month is not simple though.</p> <pre><code>(re-matches #\"(0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\\d\\d)\" \"20/02/2020\")\n</code></pre> <p>Breakdown the regex pattern:</p> <pre><code>(0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\\\\d\\\\d)\n\n(   #start of group #1\n 0?[1-9]  #  01-09 or 1-9\n |                      #  ..or\n [12][0-9]  #  10-19 or 20-29\n |   #  ..or\n 3[01]   #  30, 31\n)           #end of group #1\n  /   #  follow by a \"/\"\n   (   #    start of group #2\n    0?[1-9]  # 01-09 or 1-9\n    |   # ..or\n    1[012]  # 10,11,12\n    )   #    end of group #2\n     /   # follow by a \"/\"\n      (   #   start of group #3\n       (19|20)\\\\d\\\\d #       19[0-9][0-9] or 20[0-9][0-9]\n       )  #   end of group #3\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/common-regex-patterns/#reference","title":"Reference","text":"<ul> <li>https://mkyong.com/regular-expressions/10-java-regular-expression-examples-you-should-know</li> </ul>"},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/","title":"Matching sub sequences","text":""},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/#matching-sub-sequences","title":"Matching sub-sequences","text":"<p><code>re-seq</code> returns a lazy seq of all of the matches. The elements of the seq are the results that <code>re-find</code> would return.</p> <p><pre><code>(re-seq #\"s+\" \"Helloween\")\n</code></pre> </p>"},{"location":"reference/standard-library/regular-expressions/matching-sub-sequences/#most-common-word","title":"Most common word","text":"<p><code>re-seq</code> is used in the most common word challenge to split a string into individual words.</p> <p>Extract from Project Guttenburg the text of The importance of being Earnest by Oscar Wilde.  This returns a string of the whole book.</p> <p>The book is broken down into a collection of individual words using <code>re-seq</code> and a regular expression pattern.</p> <p>The collection of words is converted to lower case, so that <code>The</code> and <code>the</code> are not counted as separate words. <code>frequencies</code> returns a collection of tuples, each tuple being a word and a value representing how often it occurs.  This collection is sorted by the value in descending order to show the word with the most occurrences at the top.</p> <pre><code>(-&gt;&gt; (slurp \"http://www.gutenberg.org/cache/epub/844/pg844.txt\")\n     (re-seq #\"[a-zA-Z0-9|']+\")\n     (map #(clojure.string/lower-case %))\n     frequencies\n     (sort-by val dec))\n</code></pre> <p>TODO: add link to complete example.</p>"},{"location":"reference/standard-library/regular-expressions/matching-sub-strings/","title":"Matching sub strings","text":""},{"location":"reference/standard-library/regular-expressions/matching-sub-strings/#matching-sub-strings","title":"Matching sub-strings","text":"<p><code>re-find</code> returns the first match within the string, using return values similar to re-matches.</p> <p><code>nil</code> is returned when the pattern does not find a match.</p> <pre><code>(re-find #\"pump\" \"Halloween\")\n</code></pre> <p>A matching pattern without groups returns the matched string</p> <pre><code>(re-find #\"e+\" \"Halloween\")\n</code></pre> <p>Match with groups returns a vector of results</p> <p><pre><code>(re-find #\"s+(.*)(s+)\" \"success\")\n</code></pre> </p>"},{"location":"reference/standard-library/regular-expressions/matching-with-groups/","title":"Matching with regex groups","text":"<p><code>rematches</code> takes a pattern and compares it with a string.</p> <p>If the pattern does not match the string then <code>nil</code> is returned to show the function returned a false value.</p> <pre><code>(re-matches #\"pumpkin\" \"Halloween pumpkin\")\n ```\n\nIf there is an exact match and there are no groups (parens) in the regex, then the matched string is returned.\n\n```clojure\n(re-matches #\"pumpkin\" \"pumpkin\")\n</code></pre> <p>If the pattern matches but there are groups, a vector of matching strings is returned. The first element in the vector is the entire match. The remaining elements are the group matches.</p> <pre><code>(re-matches #\"Halloween(.*)\" \"Halloween pumpkin\")\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/string-replace-with-regex/","title":"String replace with regex","text":""},{"location":"reference/standard-library/regular-expressions/string-replace-with-regex/#string-replace-with-regex-pattern","title":"String replace with regex pattern","text":"<p><code>clojure.string/replace</code> takes a string, a pattern and a substring that will replace matching patterns.</p> <pre><code>(clojure.string/replace \"mississippi\" #\"i..\" \"obb\")\n</code></pre> <p>Groups can be referred to in the substring replacement</p> <p><pre><code>(clojure.string/replace \"mississippi\" #\"(i)\" \"$1$1\")\n</code></pre> </p> <p>Replace with the value of a function applied to the match:</p> <pre><code>(clojure.string/replace \"mississippi\" #\"(.)i(.)\"\n     (fn [[_ b a]]\n       (str (clojure.string/upper-case b)\n            \"--\"\n            (clojure.string/upper-case a))))\n   \"M--SS--SS--Ppi\"\n</code></pre> <p><code>clojure.string/replace-first</code> is a variation where just the first occurrence is replaced.</p>"},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/","title":"String split with regex","text":""},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/#string-splitting-using-a-regex-pattern","title":"String splitting using a regex pattern","text":"<p><code>clojure.string/split</code> takes a string to be split and a pattern to split the string with.</p> <pre><code>(clojure.string/split \"This is a string    that I am splitting.\" #\"\\s+\")\n   [\"This\" \"is\" \"a\" \"string\" \"that\" \"I\" \"am\" \"splitting.\"]\n</code></pre>"},{"location":"reference/standard-library/regular-expressions/string-split-with-regex/#most-common-words-example","title":"Most common words example","text":"<p>Extract a list of the most commonly used English words, returned as a string of words that are separated by a comma.</p> <p>The <code>#\",\"</code> regex pattern splits the string of words to form a collection of individual words, each word being its own string.</p> <pre><code>(def common-english-words\n  (set\n    (clojure.string/split\n      (slurp\n        \"http://www.textfixer.com/resources/common-english-words.txt\")\n      #\",\")))\n</code></pre> <p>TODO: add link to complete example.</p>"},{"location":"reference/standard-library/regular-expressions/sub-expression-matches/","title":"Sub-expression Matches","text":"Pattern Description ^ Matches beginning of line. $ Matches end of line. . Matches any single character except newline. Using m option allows it to match newline as well. [...] Matches any single character in brackets. [^...] Matches any single character not in brackets \\A Beginning of entire string \\z End of entire string \\Z End of entire string except allowable final line terminator. re* Matches 0 or more occurrences of preceding expression. re+ Matches 1 or more of the previous thing re? Matches 0 or 1 occurrence of preceding expression. re{ n} Matches exactly n number of occurrences of preceding expression. re{ n,} Matches n or more occurrences of preceding expression. re{ n, m} Matches at least n and at most m occurrences of preceding expression. a b (re) Groups regular expressions and remembers matched text. (?: re) Groups regular expressions without remembering matched text. (?&gt; re) Matches independent pattern without backtracking. \\w Matches word characters. \\W Matches nonword characters. \\s Matches whitespace. Equivalent to [\\t\\n\\r\\f]. \\S Matches nonwhitespace. \\d Matches digits. Equivalent to [0-9]. \\D Matches nondigits. \\A Matches beginning of string. \\Z Matches end of string. If a newline exists, it matches just before newline. \\z Matches end of string. \\G Matches point where last match finished. \\n Back-reference to capture group number \"n\" \\b Matches word boundaries when outside brackets. Matches backspace (0x08) when inside brackets. \\B Matches nonword boundaries. \\n, \\t, etc. Matches newlines, carriage returns, tabs, etc. \\Q Escape (quote) all characters up to \\E \\E Ends quoting begun with \\Q"},{"location":"reference/tagged-literals/","title":"Tagged Literals","text":"<p>Frequently used value types are afforded a \"tagged literal\" syntax. It is similar to a constructor, but this special syntax makes it de/serializable and easier to read at the REPL.</p> <p>Tagged literals start with a # followed by a symbol and a literal:</p> <p><code>#js [...]</code>- JavaScript array literal</p> <p><code>#js {...}</code> - JavaScript object literal</p> <p><code>#inst \"...\"</code> - JavaScript date literal</p> <p><code>#uuid \"...\"</code> - UUID literal</p> <p><code>#queue [...]</code> - queue literal</p>"},{"location":"reference/tagged-literals/uuid/","title":"uuid tag literal","text":"<p>A universally unique identifier (UUID).</p> <pre><code>#uuid \"8-4-4-4-12\" - numbers represent the number of hex digits\n#uuid \"97bda55b-6175-4c39-9e04-7c0205c709dc\" - actual example\n</code></pre> <p>Representing UUIDs with #uuid rather than just a plain string has the following benefits:</p> <pre><code>the reader will throw an exception on malformed UUIDs\nits UUID type is preserved and shown when serialized to edn.\n</code></pre>"},{"location":"reference/tagged-literals/uuid/#creating-uuids-clojure","title":"Creating UUIDs - Clojure","text":"<p>In Clojure, call the randomUUID method of the java.util.UUID class</p> <pre><code>(java.util.UUID/randomUUID)\n</code></pre> <p>This returns a UUID tagged literal.</p> <pre><code>(java.util.UUID/randomUUID)\n;; =&gt; #uuid \"44f3ffd7-6702-4b8a-af25-11bee4b5ec4f\"\n</code></pre> <p>Looking at the type we can see its a Java object from the java.util.UUID class:</p> <pre><code>(type (java.util.UUID/randomUUID))\n;; =&gt; java.util.UUID\n</code></pre>"},{"location":"reference/tagged-literals/uuid/#creating-uuids-clojurescript","title":"Creating UUIDs - ClojureScript","text":"<p>Randomly generate a UUID in ClojureScript:</p> <p><code>cljs.core/random-uuid</code></p> <p>To label a value as a UUID:</p> <p><code>cljs.core/uuid</code></p>"},{"location":"reference/tagged-literals/uuid/#hintuuid-does-not-validate-the-value","title":"Hint::uuid does not validate the value","text":"<p>The ClojureScript documentation states that uuid? does not perform validation.</p>"},{"location":"reference/tagged-literals/uuid/#testing-for-a-uuid","title":"Testing for a uuid","text":"<p><code>uuid?</code> tests a given value and returns true if it is a uuid tagged literal value.</p> <p><code>tagged-literal?</code> is the more general function for any tagged values.</p>"},{"location":"simple-projects/","title":"Small Projects","text":"<p>An effective way to get comfortable with Clojure is to start writing small projects.  In this section several small projects are used to walk the audience through how to create and develop a project, as well as learn some Clojure functions and functional programming techniques along the way.</p> Project Topics Description Random Clojure Function namespace vars print a random function from the Clojure standard library Encoding and decoding hash-map dictionaries transforming messages between one form and another Data Transformation transforming larger and larger data sets Test Driven Development and Kata Unit testing Unit testing and solving challenges using different approaches <p>Create a Clojure project</p> <p>Clojure CLI tools and clj-new to create a new Clojure project.</p>"},{"location":"simple-projects/generate-web-page/","title":"Generate Web Page","text":"<p>Generate a web page from Clojure code, using Hiccup</p> <p>Generate a full HTML webpage with content.</p> <p>Add a CSS library (bulma.io, bootstrap) to improve generation</p>"},{"location":"simple-projects/generate-web-page/#summary","title":"Summary","text":"<p>Generating a web page in Clojure shows how easy it is to structure data and transform that data into other structures.</p> <p>Although this kind of project is easy enough to just do in a REPL directly, using a Clojure aware editor with a Clojure project makes changes to the code far simpler, without loosing any of the immediate feedback of the REPL.</p> <p>Most Clojure developers use the REPL by evaluating code in the editor showing the source code from the project.</p> <p> Practicalli Web Services book shows how to build websites, create self-documented API's, manage Web Application servers and use databases to persist data.</p>"},{"location":"simple-projects/random-clojure-function/","title":"Random Clojure Function","text":"<p>A simple application that returns a random function from the <code>clojure.core</code> namespace, along with the function argument list and its description (from the doc-string)</p> <p>There are 659 functions in <code>clojure.core</code> namespace and 955 in the standard library (as of June 2020).  These functions are learned over time as experience is gained with Clojure.</p> Project: Random Clojure function <p> practicalli/random-clojure-function repository contains a Clojure project with an example solution</p>"},{"location":"simple-projects/random-clojure-function/#live-coding-video-walk-through","title":"Live Coding Video walk-through","text":"<p>A Live coding video walk-through of this project shows how this application was developed, using Spacemacs editor and CircleCI for continuous integration.</p>  -M flag superseeds -A flag <p>The <code>-M</code> flag replaced the <code>-A</code> flag when running code via <code>clojure.main</code>, e.g. when an alias contains <code>:main-opts</code>.  The <code>-A</code> flag should be used only for the specific case of including an alias when starting the Clojure CLI built-in REPL.</p> <p> </p>"},{"location":"simple-projects/random-clojure-function/#create-a-project","title":"Create a project","text":"<p>Use the <code>:project/create</code>  Practicalli Clojure CLI Config to create a new Clojure project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/random-function\n</code></pre> <p>This project has a <code>deps.edn</code> file that includes the aliases</p> <ul> <li><code>:test</code> - includes the <code>test/</code> directory in the class path so unit test code is found</li> <li><code>:runner</code> to run the Cognitect Labs test runner which will find and run all unit tests</li> </ul>"},{"location":"simple-projects/random-clojure-function/#repl-experiments","title":"REPL experiments","text":"<p>Open the project in a Clojure-aware editor or start a Rebel terminal UI REPL</p> Clojure EditorRebel REPL <p>Open the <code>src/practicalli/random-function.clj</code> file in a Clojure aware editor and start a REPL process (jack-in)</p> <p>Optionally create a rich comment form that will contain the expressions as the design of the code evolves, moving completed functions out of the comment forms so they can be run by evaluating the whole namespace. <pre><code>(ns practicalli.random-function)\n\n(comment\n  ;; add experimental code here\n)\n</code></pre></p> <p>Open a terminal and change to the root of the Clojure project created, i.e. the directory that contains the <code>deps.edn</code> file.</p> <p>Start a REPL that provides a rich terminal UI <pre><code>clojure -M:repl/reloaded\n</code></pre> <code>require</code> will make a namespace available from within the REPL <pre><code>(require '[practicalli.random-function])\n</code></pre> Change into the <code>random-function</code> namespace to define functions <pre><code>(in-ns 'practicalli.random-function')\n</code></pre> Reload changes made to the <code>src/practicalli/random_function.clj</code> file using the <code>require</code> function with the <code>:reload</code> option.  <code>:reload</code> forces the loading of all the definitions in the namespace file, overriding any functions of the same name in the REPL. <pre><code>(require '[practicalli.random-function] :reload)\n</code></pre></p> <p>Copy finished code into the source code files</p> <p>Assuming the code should be kept after the REPL is closed, save the finished versions of function definitions into the source code files.  Use Up and Down keys at the REPL prompt to navigate the history of expressions</p> <p>List all the public functions in the <code>clojure.core</code> namespace using the <code>ns-publics</code> function</p> <pre><code>(ns-publics 'clojure.core)\n</code></pre> <p>The hash-map keys are function symbols and the values are the function vars</p> <pre><code>{+' #'clojure.core/+',\n decimal? #'clojure.core/decimal?,\n sort-by #'clojure.core/sort-by,\n macroexpand #'clojure.core/macroexpand\n ,,,}\n</code></pre> <p>The <code>meta</code> function will return a hash-map of details about a function, when given a function var.</p> <pre><code>(meta #'map)\n</code></pre> <p>The hash-map has several useful pieces of information for the application, including <code>:name</code>, <code>:doc</code>, and <code>:arglists</code></p> <pre><code>;; =&gt; {:added \"1.0\",\n;;     :ns #namespace[clojure.core],\n;;     :name map,\n;;     :file \"clojure/core.clj\",\n;;     :static true,\n;;     :column 1,\n;;     :line 2727,\n;;     :arglists ([f] [f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 &amp; colls]),\n;;     :doc\n;;     \"Returns a lazy sequence consisting of the result of applying f to\\n  the set of first items of each coll, followed by applying f to the\\n  set of second items in each coll, until any one of the colls is\\n  exhausted.  Any remaining items in other colls are ignored. Function\\n  f should accept number-of-colls arguments. Returns a transducer when\\n  no collection is provided.\"}\n</code></pre> <p>To use the <code>meta</code> function, the values from the <code>ns-publics</code> results should be used.</p> <pre><code>(vals (ns-publics 'clojure.core))\n</code></pre> <p><code>rand-nth</code> will return a random function var from the sequence of function vars</p> <pre><code>(rand-nth (vals (ns-publics 'clojure.core)))\n</code></pre> <p>A single function var is returned, so then the specific meta data can be returned.</p> <pre><code>(meta (rand-nth (vals (ns-publics 'clojure.core))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#define-a-name-for-all-functions","title":"Define a name for all functions","text":"<p>Edit the <code>src/practicalli/random-function.clj</code> file and define a name for the collection of all public functions from <code>clojure.core</code></p> <pre><code>(def standard-library\n  \"Fully qualified function names from clojure.core\"\n  (vals (ns-publics 'clojure.core)))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#write-unit-tests","title":"Write Unit Tests","text":"<p>From the REPL experiments we have a basic approach for the application design, so codify that design by writing unit tests.  This will also highlight regressions during the course of development.</p> <p>Edit the file <code>test/practicalli/random_function_test.clj</code> and add unit tests.</p> <p>The first test check the standard-library-functions contains entries.</p> <p>The second test checks the -main function returns a string (the function name and details).</p> src/practicalli/random_function_test.clj<pre><code>(ns practicalli.random-function-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [practicalli.random-function :as random-fn]))\n\n(deftest standard-library-test\n  (testing \"Show random function from Clojure standard library\"\n    (is (seq random-fn/standard-library-functions))\n    (is (string? (random-fn/-main)))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#update-the-main-function","title":"Update the main function","text":"<p>Edit the <code>src/practicalli/random-function.clj</code> file.  Change the <code>-main</code> function to return a string of the function name and description.</p> src/practicalli/random-function.clj<pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (let [function-details (meta (rand-nth standard-library-functions))]\n    (str (function-details :name) \"\\n  \" (function-details :doc)))\n  )\n</code></pre> Cognitect Test Runner <p>Run the tests with the Congnitect test runner via the <code>test</code> function in the <code>build.clj</code> file. ```shell clojure -T:build test</p> <p>```</p> Kaocha Test Runner <p>Run the tests with the Kaocha test runner using the alias <code>:test/run</code> from Practicalli Clojure CLI config ```shell clojure -M:test/run</p> <p>```</p>"},{"location":"simple-projects/random-clojure-function/#running-the-application","title":"Running the application","text":"<p>Use the clojure command with the main namespace of the application.  Clojure will look for the -main function and evaluate it.</p> <pre><code>clojure -M -m practicalli.random-function\n</code></pre> <p>This should return a random function name and its description.  However, nothing is returned.  Time to refactor the code.</p>"},{"location":"simple-projects/random-clojure-function/#improving-the-code","title":"Improving the code","text":"<p>The tests pass, however, no output is shown when the application is run.</p> <p>The main function returns a string but nothing is sent to standard out, so running the application does not return anything.</p> <p>The <code>str</code> expression could be wrapped in a println, although that would make the result harder to test and not be very clean code.  Refactor the <code>-main</code> to a specific function seems appropriate.</p> <p>Replace the <code>-main-test</code> with a <code>random-function-test</code> that will be used to test a new function of the same name which will be used for retrieving the random Clojure function.</p> <pre><code>(deftest random-function-test\n  (testing \"Show random function from Clojure standard library\"\n    (is (seq SUT/standard-library-functions))\n    (is (string? (SUT/random-function SUT/standard-library-functions)))))\n</code></pre> <p>Create a new function to return a random function from a given collection of functions, essentially moving the code from <code>-main</code>.</p> <p>The function extracts the function <code>:name</code> and <code>:doc</code> from the metadata of the randomly chosen function.</p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :name) \"\\n  \" (function-details :doc) \"\\n  \")))\n</code></pre> <p>Update the main function to call this new function.</p> <pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (println (random-function standard-library-functions)))\n</code></pre> <p>Run the tests again.</p> <p>If the tests pass, then run the application again</p> <pre><code> clojure -M -m practicalli.random-function\n</code></pre> <p>A random function and its description are displayed.</p>"},{"location":"simple-projects/random-clojure-function/#adding-the-function-signature","title":"Adding the function signature","text":"<p>Edit the <code>random-function</code> code and add the function signature to the string returned by the application.</p> <p>Format the code so it is in the same structure of the output it produces, making the code clearer to understand.</p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :name)\n    \"\\n  \" (function-details :doc)\n    \"\\n  \" (function-details :arglists))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#add-more-namespaces","title":"Add more namespaces","text":"<p>All current namespaces on the classpath can be retrieved using the <code>all-ns</code> function.  This returns a lazy-seq, <code>(type (all-ns))</code></p> <pre><code>(all-ns)\n</code></pre> <p>Using the list of namespace the <code>ns-publics</code> can retrieve all functions across all namespaces.</p> <p>Create a helper function to get the functions from a namespace, as this is going to be used in several places.</p> <pre><code>(defn function-list\n  [namespace]\n  (vals (ns-publics namespace)))\n</code></pre> <p>This function can be mapped over all the namespaces to get a sequence of all function vars.  Using <code>map</code> creates a sequence for each namespace, returned as a sequence of sequences.  Using <code>mapcat</code> will concatenate the nested sequences and return a flat sequence of function vars.</p> <pre><code>(mapcat #(vals (ns-publics %)) (all-ns))\n</code></pre> <p>Bind the results of this expression to the name <code>all-public-functions</code>.</p> <pre><code>(def available-namespaces\n  (mapcat #(vals (ns-publics %)) (all-ns)))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#control-which-namespaces-are-consulted","title":"Control which namespaces are consulted","text":"<p>There is no way to control which library we get the functions from, limiting the ability of our application.</p> <p>Refactor the main namespace to act differently based on arguments passed:</p> <ol> <li> <p>If no arguments are passed then all public functions are used to pull a random function from.</p> </li> <li> <p>If any argument is passed, the argument should be used as the namespace to pull a random function from.  The argument is assumed to be a string.</p> </li> </ol> <p><code>ns-publics</code> function needs a namespace as a symbol, so the <code>symbol</code> function is used to convert the argument.</p> <pre><code>(symbol \"clojure.string\")\n</code></pre> <p>The <code>-main</code> function uses <code>[&amp; args]</code> as a means to take multiple arguments. All arguments are put into a vector, so the symbol function should be mapped over the elements in the vector to create symbols for all the namespaces.</p> <p>Use an anonymous function to convert the arguments to symbols and retrieve the list of public functions from each namespace.  This saves mapping over the arguments twice.</p> <p><code>mapcat</code> the function-list function over all the namespaces, converting each namespace to a symbol.</p> <pre><code>(mapcat #(function-list (symbol %)) args)\n</code></pre> <p>Update the main function with an if statement.  Use <code>seq</code> as the condition to test if a sequence (the argument vector) has any elements (namespaces to use).</p> <p>If there are arguments, then get the functions for the specific namespaces.</p> <p>Else return all the functions from all the namespaces.</p> <pre><code>(defn -main\n  \"Return a function name from the Clojure Standard library\"\n  [&amp; args]\n  (if (seq args)\n    (println (random-function (mapcat #(function-list (symbol %)) args)))\n    (println (random-function standard-library-functions))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#use-the-fully-qualified-name-for-the-namespace","title":"Use the fully qualified name for the namespace","text":"<p>Now that functions can come from a range of namespaces, the fully qualified namespace should be used for the function, eg. domain/namespace</p> <pre><code>(:ns (meta (rand-nth standard-library-functions)))\n</code></pre> <p>Update the random function to return the domain part of the namespace, separated by a <code>/</code></p> <pre><code>(defn random-function\n  [function-list]\n  (let [function-details (meta (rand-nth function-list))]\n    (str (function-details :ns) \"/\" (function-details :name)\n         \"\\n  \" (function-details :arglists)\n         \"\\n  \" (function-details :doc))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#use-all-available-namespaces-by-default","title":"Use all available namespaces by default","text":"<p>Define a name to represent the collection of all available namespaces, in the context of the running REPL.</p> <pre><code>(def all-public-functions\n  \"Fully qualified function names from available\"\n  (mapcat #(vals (ns-publics %)) (all-ns)))\n</code></pre> <p>Update the <code>-main</code> function to use all available namespaces if no arguments are passed to the main function.</p> <pre><code>(defn -main\n  \"Return a random function and its details\n  from the available namespaces\"\n  [&amp; args]\n  (if (seq args)\n    (println (random-function (mapcat #(function-list (symbol %)) args)))\n    (println (random-function all-public-functions))))\n</code></pre>"},{"location":"simple-projects/random-clojure-function/#follow-on-idea-convert-to-a-web-service","title":"Follow-on idea: Convert to a web service","text":"<p>Add http-kit server and send  information back as a plain text, html, json and edn</p>"},{"location":"simple-projects/random-clojure-function/#follow-on-idea-convert-to-a-library","title":"Follow-on idea: Convert to a library","text":"<p>Convert the project to a library so this feature can be used as a development tool for any project.</p> <p>Add functionality to list all functions from all namespaces or a specific namespace, or functions from all namespaces of a particular domain, e.g <code>practicalli</code> or <code>practicalli.app</code></p>"},{"location":"simple-projects/split-the-bill/","title":"Split the bill","text":"<p>In a restaurant a group of friends and relatives are having a reunion dinner after a year of not seeing each other.</p> <p>Once the meal comes to an end, its time to pay the bill.  So how would you write code to split the bill?</p> <p>Start with the simplest possible approach, with everyone paying the same.</p>"},{"location":"simple-projects/split-the-bill/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/split-the-bill\n</code></pre> <pre><code>(str \"Create code to calculate the bill, including what each person should pay\")\n</code></pre> <p>Tke a look at the Who am I section for ideas on how to model the bill.  Also look at More Than Average for ideas on how to write code to work out how to pay the bill.</p>"},{"location":"simple-projects/split-the-bill/#paying-what-was-ordered","title":"Paying what was ordered","text":"<p>As not everyone had eaten the same amount of food or arrived at the same time, then there was an ask for everyone to pay just what they ordered.</p> <p>So create a collection to capture what each person ordered and create an itemised bill so each person knows what they should pay.</p> <p>Define a detailed bill based on what each person ordered, then create an itemised bill based on each persons order</p> <p>Now it was realised that what everyone ordered is not what everyone ate.  So now we need to take the order and create an itemised bill based on what everyone actually ate (lets suspend believe here a little and assume everyone knows exactly what they ate, and is honest about it).</p> <p>Define a detailed bill based on what each person ordered, then create an itemised bill based on each person actually ate</p>"},{"location":"simple-projects/split-the-bill/#spliting-the-bill-with-a-social-group","title":"Spliting the bill with a Social Group","text":"<p>Extend the exercise by splitting bills over multiple events and activities with multiple people.</p>"},{"location":"simple-projects/tripple-lock/","title":"Triple Lock","text":"<p>A new safe too keep all the richest you will gain from becoming a Clojure developer (hopefully).  The safe has a 3 combination lock to protect your new found wealth, but just how safe is the safe?</p>"},{"location":"simple-projects/tripple-lock/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/triple-lock\n</code></pre>"},{"location":"simple-projects/tripple-lock/#designing-the-combination-lock","title":"Designing the combination lock","text":"<p>Lets consider how we would create such a combination lock in Clojure.</p> <ul> <li>The combination is managed by three tumbler wheels</li> <li>Each tumbler wheel has the same range of numbers on then, 0 to 9</li> </ul> <p>Each tumbler wheel could have all the numbers it contains within a Collection in Clojure.  The simplest approach would be to put the numbers 0 to 9 into a Vector (an array-like collection).</p> <pre><code>[0 1 2 3 4 5 6 7 8 9]\n</code></pre> <p>As the numbers on the tumbler wheel are just a range between 0 and 9, then rather than type out all the numbers we can use the <code>range</code> function to generate all the numbers for us.</p> <p>When we give the range function one argument, it will create all the whole numbers from 0 to the number before that of the argument.  In the following example, we give <code>range</code> the argument of 10 and we receive the numbers from 0 to 9.</p> <pre><code>(range 10)\n</code></pre> <p>You can also give <code>range</code> two arguments, such as '(range 5 15)'.</p> <p>Be careful not to call the <code>range</code> function by itself, or it will try and generate an infinite range of numbers (until your computer memory is all used up).</p>"},{"location":"simple-projects/tripple-lock/#create-all-the-combinations","title":"Create all the Combinations","text":"<p>Complete the following code (replacing the ,,,) to generate all the possible combinations of the lock</p> <pre><code>(for [tumbler-1 (range 10)\n      ,,,     ,,,\n      ,,,     ,,,]\n [tumbler-1 ,,,   ,,,])\n</code></pre> <p>Instead of showing all the possible combinations, count all the combinations and return the total number of combinations</p> <p>Take the code from the combinations and wrap it in the count function</p> <pre><code>;; now count the possible combinations\n(count\n\n         )\n</code></pre> <p>To make our lock harder to break into, we should only allow the combinations where each tumbler wheel has a different number.  So you cannot have combinations like 1-1-1, 1-2-2, 1-2-1, etc.</p> <p>How many combinations does that give us?</p> <p>Complete the following code to create a 3-tumbler wheel combination lock, where none of the numbers are the same</p> <p>Hint: Beware not to enter (range) without an argument as Clojure may try and evaluate infinity</p> <pre><code>(count (for [tumbler-1 (range 10)\n             ,,,     ,,,\n             ,,,     ,,,\n             :when (or (= tumbler-1 tumbler-2)\n                       ,,,\n                       ,,,)]\n         [tumbler-1 ,,,   ,,,]))\n</code></pre> Suggested solution <p>Suggested solution to the completed 3-lock challenges. <pre><code>;; a 3 combination padlock\n\n;; model the combinations\n(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)]\n [tumbler-1 tumbler-2 tumbler-3])\n\n\n;; now count the possible combinations\n(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)]\n         [tumbler-1 tumbler-2 tumbler-3]))\n\n\n(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)\n             :when (or (= tumbler-1 tumbler-2)\n                       (= tumbler-2 tumbler-3)\n                       (= tumbler-3 tumbler-1))]\n         [tumbler-1 tumbler-2 tumbler-3]))\n\n;; lets look at the combinations again, we can see that there is always at least 2 matching values.  This is probably the opposite of what we want in real life.\n(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)\n      :when (or (= tumbler-1 tumbler-2)\n                (= tumbler-2 tumbler-3)\n                (= tumbler-3 tumbler-1))]\n  [tumbler-1 tumbler-2 tumbler-3])\n</code></pre></p>"},{"location":"simple-projects/data-transformation/","title":"Data Transformation","text":"<p>In a sense all Clojure project are about data transformation, however, these projects will introduce you to many techniques used to transform larger and larger data sets.</p> <p></p> Project Topics Overview Most common word regex filter re-seq sort-by Find the most common word in a give book that is not a common English word"},{"location":"simple-projects/data-transformation/most-common-word/","title":"Most common word","text":"<p>In this challenge we would like you to find the most used word in a book. The word should not be part of the common English words (i.e. the, a, i, is).</p> <p>This functionality is useful for generating word maps or identifying patterns across data sets.</p> <p></p> <p>Copyright free books for use are available via Project Guttenburg, e.g. \u201cThe Importance of Being Earnest\u201d by Oscar Wilde.</p>"},{"location":"simple-projects/data-transformation/most-common-word/#suggested-approach","title":"Suggested approach","text":"<p>A suggested approach to find the most common word:</p> <ul> <li>Pull the content of the book into a collection</li> <li>Use a regular expression to create a collection of individual words - eg. <code>#\u201d[a-zA-Z0-9|\u2019]+\u201d</code></li> <li>Remove the common English words used in the book</li> <li>Convert all the words to lower case so they match with common words source</li> <li>Count the occurrences of the remaining words (eg. each word is associated with the number of times it appears in the book)</li> <li>Sort the words by the number of the occurrences</li> <li>Reverse the collection so the most commonly used word is shown first</li> </ul>"},{"location":"simple-projects/data-transformation/most-common-word/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/common-words\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#get-the-book-contents","title":"Get the book contents","text":"<p><code>clojure.core/slurp</code> will read in a local file or a remote resource (file, web page, etc) and return a single string of the contents.</p> <pre><code>(slurp \"https://www.gutenberg.org/files/844/844-0.txt\")\n</code></pre> <p>Wrap the <code>slurp</code> expression in a <code>def</code> to bind a name to the book.</p> <pre><code>(def being-earnest (slurp \"https://www.gutenberg.org/files/844/844-0.txt\"))\n</code></pre> <p>Project Gutenberg now compresses the books with GZip, so a stream can be created to read the file and decompress it.  Then slurp is used to read in the uncompressed text of the book into a string.</p> <pre><code>(def being-earnest\n  (with-open [uncompress-text (java.util.zip.GZIPInputStream.\n                  (clojure.java.io/input-stream\n                   \"https://www.gutenberg.org/cache/epub/844/pg844.txt\"))]\n    (slurp uncompress-text)))\n ```\n\n## Individual words from the book\n\nThe book contents should be broken down into individual words.\n\nA regular expression can be used to identify word boundaries, especially where there are apostrophes and other characters.\n\n`clojure.core/re-seq` returns a new lazy sequence containing the successive matches of a pattern from a given string.  So given a sentence\n\nUsing `re-seq` to convert the first sentence of the `being-earnest` book using a regex word boundary pattern, `\\w+`.\n\n```clojure\n(re-seq #\"\\w+\" \"Morning-room in Algernon's flat in Half-Moon Street.\")\n\n;; =&gt; (\"Morning\" \"room\" \"in\" \"Algernon\" \"s\" \"flat\" \"in\" \"Half\" \"Moon\" \"Street\")\n</code></pre> <p>The result is a sequence of the individual words, however, the hyphenated words and the apostrophes have been split into separate words.</p> <p>Extending the regex pattern the results can be refined.</p> <pre><code>(re-seq #\"[\\w|'-]+\" \"Morning-room in Algernon's flat in Half-Moon Street.\")\n\n;; =&gt; (\"Morning-room in Algernon's flat in Half-Moon Street\")\n</code></pre> <pre><code>(re-seq #\"[\\w|'-]+\" being-earnest)\n</code></pre> <p>The #\"[\\w|'-]+\" is the same pattern as the more explicit pattern #\"[a-zA-Z0-9|'-]+\"</p>"},{"location":"simple-projects/data-transformation/most-common-word/#removing-common-english-words","title":"Removing common English words","text":"<p>In any book the most common word its highly likely to be a common English word (the, a, and, etc.).  To make the most common word in any book more specific, the common English words should be removed.</p> <p><code>common-english-words.csv</code> contains comma separate words.</p> <p>Using slurp and a regular expression the individual words can be extracted into a collection.</p> <p>Rather than <code>re-seq</code> the <code>clojure.string/split</code> can be used.  This is a more specific function for splitting a string using a regular expression pattern, in this case the pattern for a comma, <code>#\",\"</code>.</p> <pre><code> (clojure.string/split (slurp \"common-english-words.csv\") #\",\")\n</code></pre> <p>An additional step is to place the common English words into a Clojure set, a data structure which contains a unique set of values.</p> <pre><code> (set (clojure.string/split (slurp \"common-english-words.csv\") #\",\"))\n</code></pre> <p>The advantage of using a set for the common English words is that the data structure can be used as a predicate to remove matching words.  So a common English words set can be used to remove the common English words from <code>being-earnest</code> book.</p> <p>Define a name for the common English words set.</p> <pre><code>(def common-english-words (set (clojure.string/split (slurp \"common-english-words.csv\") #\",\")))\n</code></pre> <p>This can also be written using the threading macro, to show the sequential nature of the data transformation.</p> <pre><code>(def common-english-words\n  (-&gt; (slurp \"common-english-words.csv\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre> <p>The <code>common-english-words</code> set can now be used with the <code>being-earnest</code> book.</p> <pre><code>(remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#counting-occurrences","title":"Counting Occurrences","text":"<p><code>clojure.core/frequencies</code> takes a collection and returns a map where the keys are the unique elements from the collection and the value for each key is the number of times that element occurred in the collection.</p> <pre><code>(filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest)))\n</code></pre> <p>The resulting hash-map is not in any order.  <code>clojure.core/sort-by</code> will return the same results but sorted by a given function.  To sort a hash-map the <code>key</code> and <code>val</code> functions are function that will sort by key and value respectively.  As it is the value that has the number of occurrences, then <code>val</code> is the function to use.</p> <pre><code>(sort-by val (filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))))\n</code></pre> <p>The result is sorted from smallest to largest value.  The result could be reversed using <code>clojure.core/reverse</code> or by supplying an extra function to the <code>sort-by</code> expression.  Using greater-than, <code>&gt;</code> the result will be returned in descending order.</p> <pre><code>(sort-by val dec (filter (remove common-english-words (re-seq #\"[\\w|'-]+\" being-earnest))))\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#assembling-the-most-common-word-function","title":"Assembling the most-common-word function","text":"<p>Define a function called <code>most-common-word</code> that assembles all the previous steps.  The function should take all the values it needs for the calculation as arguments, creating a pure function without side effects.</p> <pre><code>(defn most-common-word\n  [book common-words]\n  (sort-by val &gt;\n    (frequencies\n      (remove common-words\n        (map #(clojure.string/lower-case %)\n             (re-seq #\"[\\w|'-]+\" book))))))\n</code></pre> <p>This may seem a little hard to parse, so the function definition can be re-written using a threading macro.</p> <pre><code>(defn most-common-word\n  [book common-words]\n  (-&gt;&gt; book\n       (re-seq #\"[\\w|'-]+\" ,,,)\n       (map #(clojure.string/lower-case %))\n       (remove common-words)\n       frequencies\n       (sort-by val &gt;)))\n</code></pre> <p>Call this function with the <code>being-earnest</code> book and the <code>common-english-words</code></p> <pre><code>(most-common-word being-earnest common-english-words)\n</code></pre>"},{"location":"simple-projects/data-transformation/most-common-word/#running-from-the-command-line","title":"Running from the command line","text":"<p>Update the code to take the book reference from the command line.</p> <p>Remove the <code>def</code> that hard-coded the being-earnest book.</p> <p>In the <code>most-common-word</code> wrap the book with <code>slurp</code> to read the book reference in and convert it to a string, to be processed by the rest of the expressions.</p> <p>Add a <code>-main</code> function that takes a reference for the source of the book and the source of the common words.</p> <pre><code>(ns practicalli.common-word)\n\n(defn decode-book\n  [book-gzip]\n  (with-open\n    [uncompress-text (java.util.zip.GZIPInputStream.\n                      (clojure.java.io/input-stream book-gzip))]\n    (slurp uncompress-text)))\n\n(defn common-words\n  [csv]\n  (-&gt; (slurp csv)\n      (clojure.string/split #\",\")\n      set))\n\n(defn most-common-word\n  [book-gzip common-words]\n  (-&gt;&gt; (decode book-gzip)\n       (re-seq #\"[\\w|'-]+\")\n       (map #(clojure.string/lower-case %))\n       (remove common-words)\n       frequencies\n       (sort-by val &gt;)))\n\n(defn -main\n  [book-gzip common-word-csv]\n  (most-common-word book-gzip (common-words common-word-csv)))\n</code></pre> <p>Now call the code on the command line.</p> <pre><code>clojure -m practicalli.common-word \"https://www.gutenberg.org/cache/epub/844/pg844.txt\" \"common-english-words.csv\"\n</code></pre>"},{"location":"simple-projects/encode-decode/","title":"Encoding and Decoding with Clojure","text":"<p>Projects that use a range of ciphers, from simple to more complex, to encode and decode text.</p> <p>A common approach to encoding and decoding text is to use a dictionary lookup, defined in Clojure as a hash-map. Each key-value pair provides a mapping for encoding and decoding.  Looking up a a character as a key in the map provides a value that is the encrypted character.</p> <p>These projects show several ways to transform data in Clojure.</p> Project Topics Description Boolean names to 0 or 1 hash-map get Convert boolean values to classic 1 or 0 values Caesar cipher - ROT13 seq cycle zipmap A simple alphabet rotation cipher RNA / DNA converter Convert between DNA and RNA Clacks telegram Encoding and decoding messages with Clacks"},{"location":"simple-projects/encode-decode/#examples-of-encoding","title":"Examples of Encoding","text":"<ul> <li>Portable Network Graphics for image compression</li> <li>Vorbis for music and video compression plus several commercial compression encoders</li> <li>Enigma machine - encrypted communications</li> </ul>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/","title":"Caesar Cipher ROT13","text":"<p>ROT13 is one of the simplest ciphers which uses an alphabet as a circle of characters, swapping each character with a character 13 positions later in the alphabet, assuming 26 character of an English alphabet.</p> <p>A dictionary can be generated to translate between the original alphabet and the rotated alphabet, providing a simple way to generate an encrypted message.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/caesar-cipher\n</code></pre>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#define-an-alphabet","title":"Define an alphabet","text":"<p>Define an alphabet to use as a basis for conversion.  Take the string of all characters and convert to a sequence of character types.</p> src/practicalli/caesar-cipher.clj<pre><code>(def english-alphabet\n  (seq \"abcdefghijklmnopqrstuvwxyz\"))\n</code></pre>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#generate-a-cypher","title":"Generate a cypher","text":"<p>To convert a character, first build up a cypher.  A cypher in this case is simply a hash-map that creates a dictionary lookup defining what each character should be changed to.</p> <p><code>cycle</code> creates a lazy sequence of the alphabet that continually cycles.  This provides an 'infinite' sequence from which we will take only the characters needed.</p> <pre><code>(cycle \"abcdefghijklmnopqrstuvwxyz\")\n</code></pre> <p>The dictionary is composed of the original alphabet and a new alphabet that is offset by 13 characters, half the number of characters in the dictionary.</p> <p><code>(drop 13 (cycle alphabet))</code>  will drop the first 13 characters.  As <code>cycle</code> creates an 'infinite' alphabet, there are still plenty of characters to make a second alphabet.</p> <p><code>(take 26 (drop 13 (cycle alphabet)))</code> will get a new alphabet of 26 characters, starting from the 14th character, <code>n</code>.</p> <p><code>zipmap</code> is used to join two collections together to form a hash-map, e.g. the lookup dictionary. In this case the original alphabet and the new alphabet.</p> <p><code>(zipmap alphabet (take 26 (drop 13 (cycle alphabet))))</code></p> <p>This expression is nested and can be harder to parse by those new to Clojure.  The code can be written using a threading marco, that demonstrated the flow of data transformation.</p> <p>Using the thread last macro, <code>-&gt;&gt;</code>, the result of each expression becomes the last argument for the next expression.</p> <pre><code>(-&gt;&gt; (cycle alphabet)\n     (drop 13)\n     (take 26)\n     (zipmap alphabet))\n</code></pre> <p>Using the clojure.core/replace function with the cypher hash-map and a string of text returns a converted string of text.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#define-a-function","title":"Define a function","text":"<p>Define a <code>rot13</code> function with the algorithm created.  The function takes the alphabet and the text to be encrypted.  Passing both pieces of data as arguments ensures that the function is pure, i.e. free from side effects.</p> src/practicalli/caesar-cipher.clj<pre><code>(defn rot13 [alphabet text]\n  (let [cipher (-&gt;&gt; (cycle alphabet)\n                    (drop 13)\n                    (take 26)\n                    (zipmap alphabet))]\n    (apply str (replace cipher text))))\n</code></pre> <p>Call the rot13 function with the <code>english-alphabet</code> and a sentence as a string.</p> <pre><code>(rot13 english-alphabet \"The Quick Brown Fox Jumped Over The Lazy Dog!\")\n</code></pre> <p>An encrypted copy of the sentence is returned.</p>"},{"location":"simple-projects/encode-decode/caesar-cipher-rot13/#idiomatic-improvements","title":"Idiomatic improvements","text":"<p><code>clojure.string</code> library is more idiomatic approach when working with string types.</p> <p>In the <code>practicalli.cypher-rot13</code> solution <code>apply str</code> was used to join a sequence of characters into a string.  <code>clojure.string/join</code> combines a sequence of characters into a string.</p> <p>Require the <code>clojure.string</code> namespace to use the functions contained within.  Add the require to the namespace definition of <code>practicalli.cypher-rot13</code></p> src/practicalli/caesar-cipher.clj<pre><code>(ns practicalli.ceaser-cypher\n  (:gen-class)\n  (:require [clojure.string :as string]))\n</code></pre> <p>Update the <code>rot13</code> function to use <code>clojure.string/join</code> rather than <code>apply str</code>.</p> <pre><code>(defn rot13 [alphabet text]\n  (let [cipher (-&gt;&gt; (cycle alphabet)\n                    (drop 13)\n                    (take 26)\n                    (zipmap alphabet))]\n    (string/join (replace cipher text))))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/","title":"Clacks Messages","text":"<p>In the 33rd Discworld novel, Going Postal, messages are sent faster than a speeding horse via the Clacks system.  The Clacks system composes of a series of towers spread across a continent with each tower sending a light signal to the next tower using combinations of lights for each character in the message.  Each tower sees a grid of lights from a distant tower and sends the message on to the next tower.</p> <p>The Clacks system was introduced in the 24th Discworld novel called \"The Fifth Elephant\". \"Going Postal\" elaborates the full history of the Clacks system.</p>"},{"location":"simple-projects/encode-decode/clacks/#the-challenge","title":"The Challenge","text":"<p>Create a Clacks encoder that converts any English language message into its corresponding clacks signal, based on the Clacks alphabet as defined by the board game of the same name.</p> <p>The board game defines the alphabet as a 2 by 3 grid (although in the Discworld its actually 8 large squares).  Naturally, the interpreter also converts the Clacks signal back into an English message too.</p> <p></p>"},{"location":"simple-projects/encode-decode/clacks/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/clacks-messenger\n</code></pre> <p>This project has a <code>deps.edn</code> file that includes the aliases</p> <ul> <li><code>:test</code> - includes the <code>test/</code> directory in the class path so unit test code is found</li> <li><code>:runner</code> to run the Cognitect Labs test runner which will find and run all unit tests</li> </ul>"},{"location":"simple-projects/encode-decode/clacks/#representing-a-clack","title":"Representing a Clack","text":"<p>For each clack, the light pattern is read from the top of the first column to the bottom, then from the top of the second column to the bottom.  A light in a position represents a 1 value and no light represents a 0 value.  This gives us our 6 number pattern for each clack in the alphabet.</p> <p>The initial data structure chosen was essentially just modelling each individual clack.  Since a clack is a 2x3 structure, the simplest way to represent a clacks is to have a vector that contains 2 vectors, each with three elements.</p> <p>So a simple expression of the letter a in the clacks alphabet would be:</p> <pre><code>[[0 1 0][0 0 1]]\n</code></pre> <p>Therefore we could define a single letter of our alphabet as follows:</p> <pre><code>(def a [[0 1 0][0 0 1]])\n</code></pre> <p>Before defining the complete alphabet using this data structure, test this is the right data structure for the conversion process.</p>"},{"location":"simple-projects/encode-decode/clacks/#test-simple-conversion","title":"Test simple conversion","text":"<p>Define a function to convert a single character into a clack:</p> <pre><code>(defn character-&gt;clack [character]\n  (if (= character \"a\")\n    a\n    (str \"Sorry, character is not yet in the alphabet, please create a pull request\")))\n</code></pre> <p>Calling the function converts a string into the corresponding clack</p> <pre><code>(character-&gt;clack \"a\")\n</code></pre> <p>Clojure function naming</p> <p><code>-&gt;</code> is a naming convention to indicate a function is specifically transforming to a data format.  For example, <code>json-&gt;clj-map</code> would be a generic function for transforming json to Clojure hash-map</p> <p>The code is simple for a single character, however, would require a lot of redundant code to convert the whole alphabet.  We would need either a deeply nested set of if statements or a very long <code>cond</code> function, neither of which seems to be a particularly functional approach or idiomatic Clojure.</p> <p>If a <code>cond</code> statement was used, how would a clacks be converted back into a character?</p> <p>So perhaps we need to change the data structure, one that provides an easy way to map to values together.</p> <p>Also, there seems no value in mapping values to a 2x3 grid as long as we consistently express a clack.</p>"},{"location":"simple-projects/encode-decode/clacks/#define-the-alphabet","title":"Define the alphabet","text":"<p>A hash map associates each key with a value and are used to create self-describing data. For example a person could be described as a hash-map</p> <pre><code>{:name \"Jenny Jetpack\" :age \"21\" :twitter \"jenjetpack\"}\n</code></pre> <p>Clojure keywords are often used for the keys because keywords can be used as a function with a map as an argument.  This will return the value associated with the keyword in the map.</p> <p>The new design for the clacks data structure associates a keyword of each letter of the alphabet with its corresponding clacks light pattern code</p> <pre><code>{:a [0 1 0 0 0 1]}\n</code></pre> <p>Test the design by defining enough letters for the clacks alphabet to convert some simple words, i.e bat</p> <pre><code>(def alphabet {:a [0 1 0 0 0 1]\n               :b [0 0 1 0 1 0]\n               :t [1 0 0 1 1 1]})\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#testing-the-map-design","title":"Testing the map design","text":"<p>Use a keyword to lookup the value of its clack code</p> <pre><code>(:a alphabet)\n\n;; =&gt; [0 1 0 0 0 1]\n</code></pre> <p>Create a simple function to convert a single character to its Clacks representation, referred to a clack.</p> <pre><code>(defn character-&gt;clack [character]\n    ((keyword character) alphabet))\n</code></pre> <p>The <code>-&gt;</code> character is part of the function name.  This is a Clojure naming convention used when the function you are defining converts from one type to another.</p> <p>And call the function as follows</p> <pre><code>(character-&gt;clack \"a\")\n\n;; =&gt; [0 1 0 0 0 1]\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#converting-a-word","title":"Converting a word","text":"<p>Now we want to convert a whole word to a clacks sequence.  It seemed the easiest way to convert a whole word was to convert each letter at a time using the map to look up each clack code, returning all the clacks codes in a sequence.</p> <p>So we redefined the <code>string-&gt;clacks</code> function to take in a whole word.</p> <p>We used the <code>map</code> function to apply a conversion function over each element in the word (each element of the string).  This conversion function called <code>clacksify</code>.</p> <pre><code>(defn clacksify [letter]\n  (let [character (str letter)]\n  (alphabet (keyword character))))\n\n(defn string-&gt;clacks [word]\n  (map clacksify word))\n</code></pre> <p>Now we could convert any word that used the letters of our limited alphabet.  We chose bat as a simple word.</p> <pre><code>(string-&gt;clacks \"bat\")\n</code></pre> <p>As we are passing a string and not a keyword to the <code>clacksify</code> function, then we first convert the string to a keyword using the <code>keyword</code> function.</p>"},{"location":"simple-projects/encode-decode/clacks/#converting-the-clack-to-a-string","title":"Converting the clack to a string","text":"<p>Is there a simple way to look up a key given a value that is unique in the map?</p> <p>All Clack codes are unique in the map, but there did not seem to be a simple expression to find the key when given a value.</p> <p>We could have created a second mapping, however having two maps seemed redundant and a potential cause for silly bugs.</p> <p>The answer was simple once we found it.  As the clack codes are unique, they could be used as keys for the letter values, we just needed to swap the map around.  Swapping a map's keys and values was done by writing a <code>reverse-map</code> function.</p> <pre><code>(defn reverse-map\n  \"Reverse the keys and value pairs in a map.\n  Allows the map to be used to convert from a clack to a letter without defining a second map\"\n  [m]\n  (into {} (map (fn [[a b]] [b a]) m)))\n</code></pre> <p>So we defined the function <code>declacksify</code> which takes a clack code and returns its corresponding character.  The clack code returns the corresponding keyword rather than a character, so we use the <code>name</code> function to convert the keyword into a character name.</p> <pre><code>(defn declacksify [clack]\n  (name ((reverse-map alphabet) clack)))\n\n(defn clacks-&gt;string [clacks]\n  (map declacksify clacks))\n</code></pre> <p>So calling these functions with a clacks</p> <pre><code>(declacksify  [1 0 0 1 1 1])\n;; =&gt; \"t\"\n\n(clacks-&gt;string [[0 0 1 0 1 0] [0 1 0 0 0 1] [1 0 0 1 1 1]])\n;; =&gt; (\"b\" \"a\" \"t\")\n</code></pre> <p>At this point you may be thinking that using keywords to represent the characters of the alphabet may not be the most effective.  Using keywords has required more code to be written, adding to the complexity of the solution.</p>"},{"location":"simple-projects/encode-decode/clacks/#tidy-output","title":"Tidy output","text":"<p><code>clacks-&gt;string</code> function returns the right result, but not quite in the format required.  Rather than a single string a sequence of characters is returned.</p> <p>Using the <code>map</code> function we can apply the <code>str</code> function over the resulting characters to give a single string.</p> <pre><code>(defn clacks-&gt;string [clacks]\n(map str (map declacksify clacks)))\n</code></pre> <p>Using <code>clojure.string/join</code> is a more idiomatic approach to converting a sequence of characters to a string</p> <pre><code>(require '[clojure.string :as string])\n\n(defn clacks-&gt;string [clacks]\n  (string/join (map declacksify clacks)))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#refactor-dictionary-design","title":"Refactor dictionary design","text":"<p>Converting characters to keywords and back again seem redundant when characters themselves can be used as keys in a hash-map.</p> <p>Using keywords is problematic when it comes to the space character as a keyword cannot be a space.  Using <code>:-</code> to represent a space required the clacksification and declacksification functions to convert between <code>:-</code> and the space character.  This also prevents hyphenated words working in the Clacks system.</p> <p>Refactor the dictionary to use a string for each character as the keys in the map, instead of Clojure keywords.  This solves the issue with space and other special characters.</p> <pre><code>(def dictionary\n  {\"a\"  [0 1 1 0 0 0 0 1]\n   \"b\"  [0 1 1 0 0 0 1 0]\n   \"c\"  [0 1 1 0 0 0 1 1]\n   \"d\"  [0 1 1 0 0 1 0 0]\n   \"e\"  [0 1 1 0 0 1 0 1]\n   ,,,})\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#refactor-namespace","title":"Refactor namespace","text":"<p>As the dictionary can be quite large to represent in code, move the dictionary definition to its own namespace.</p> <p>Use a more specific name for the dictionary, describing what languages the dictionary is used for</p> <pre><code>(def english-&gt;clacks\n  {\"a\"  [0 1 1 0 0 0 0 1]\n   \"b\"  [0 1 1 0 0 0 1 0]\n   \"c\"  [0 1 1 0 0 0 1 1]\n   \"d\"  [0 1 1 0 0 1 0 0]\n   \"e\"  [0 1 1 0 0 1 0 1]\n   ,,,})\n</code></pre> <p>A dictionary is required to translate from Clacks to English to decode the messages. Rather than write the reverse mappings for each character in the dictionary, in effect creating a second directory for the same two languages, use a function to invert the map by swapping keys and values.</p> <p><code>clojure.set/map-invert</code> will swap each key/value pair in the map so the key becomes the value and the value becomes the key.</p> <p>Define a <code>clacks-&gt;english</code> dictionary that holds the result of the <code>map-invert</code> function call</p> <pre><code>(ns practicalli.clacks-dictionary\n  (:require [clojure.set]))\n\n(def clacks-&gt;english { ,,, })\n\n(def clacks-&gt;english (clojure.set/map-invert english-&gt;clacks))\n</code></pre> <p>Require the dictionary namespace using the alias <code>dictionary</code> to give the dictionary names context when used in the main namespace.</p> <p>Also require <code>clojure.string</code> using the alias <code>string</code> to use the join function.</p> <pre><code>(ns practicalli.clacks-messenger\n  (:require [practicalli.clacks-dictionary :as dictionary]\n            [clojure.string :as string]))\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#removing-side-effects","title":"Removing side effects","text":"<p>Designing pure functions, those that receive all their data via arguments, is a common way to remove side effects.</p> <p>Include the dictionary as an argument to each of the functions.  This ensures that each function is pure and prevents side effects (side causes).</p> <pre><code>(defn character-&gt;clack [char dictionary]\n  (let [character (str char)]\n    (get dictionary character)))\n\n(defn message-&gt;clacks [message dictionary]\n  (map #(character-&gt;clack % dictionary) message))\n\n(defn clack-&gt;character [clack dictionary]\n  (get (clojure.set/map-invert dictionary) clack))\n\n(defn clack-&gt;character [clack dictionary]\n  (get dictionary-inverted clack))\n\n;; Create a clacks code back to a message\n\n(defn clacks-&gt;message [clacks dictionary]\n  (string/join (map #(clack-&gt;character % dictionary) clacks)))\n</code></pre> <p>Test the updated functions by calling them via the REPL</p> <pre><code>(message-&gt;clacks \"cab\" dictionary/english-&gt;clacks)\n;; =&gt; ([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0])\n\n(message-&gt;clacks \"cab cab\" dictionary/english-&gt;clacks)\n;; =&gt; ([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0] [0 0 0 0 0 0 0 0] [0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0])\n\n;; Create a character from a clack code\n\n;; test data\n(clacks-&gt;message '([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0]) dictionary/english-&gt;clacks)\n\n(clacks-&gt;message\n '([0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0] [0 0 0 0 0 0 0 0] [0 1 1 0 0 0 1 1] [0 1 1 0 0 0 0 1] [0 1 1 0 0 0 1 0]) dictionary)\n</code></pre>"},{"location":"simple-projects/encode-decode/clacks/#use-alternative-dictionaries","title":"Use alternative dictionaries","text":"<p>Thanks to a flexible design with no side effects or side causes then its really easy to replace the English language alphabet with another language that can be encoded into Clack codes.</p> <p>All that is required is to define a dictionary for another language.  So languages based on the greek, latin or cyrillic alphabet could be send if a suitable alphabet with clack codes is supplied.</p>"},{"location":"simple-projects/encode-decode/convert-boolean-values/","title":"Convert boolean values","text":""},{"location":"simple-projects/encode-decode/convert-boolean-values/#convert-boolean-true-false-to-1-and-0","title":"Convert boolean true false to 1 and 0","text":"<p>A very simple example of encoding and decoding is converting the Clojure values of <code>true</code> and <code>false</code> to <code>1</code> and <code>0</code> respectively.</p> <p>Using <code>1</code> for true and <code>0</code> for false has been a common idiom in programming languages, especially where a language did not include <code>true</code> and <code>false</code> syntax.</p>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#define-an-association-between-values","title":"Define an association between values","text":"<p>Define a Clojure <code>hash-map</code> to associate the Clojure boolean <code>true</code> an <code>false</code> values to <code>1</code> and <code>0</code> respectively</p> <pre><code>{false 0\n true 1}\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#find-an-associated-value-for-the-conversion","title":"Find an associated value for the conversion","text":"<p>Using the <code>get</code> function the <code>boolean-value</code> is used to find a matching key in the map and if found the value that key is associated is returned.</p> <pre><code>(get {false 0 true 1} boolean-value)\n</code></pre> <p>Example:</p> <pre><code>(get {false 0 true 1} true)\n</code></pre> <p>A map can be called, just like a function.  the <code>boolean-value</code> is passed to the map as a function argument. As with the <code>get</code> expression, if the map contains the key the associated value is returned.</p> <pre><code>({false 0 true 1} boolean-value)\n</code></pre> <p>Example:</p> <pre><code>({false 0 true 1} true)\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#convert-multiple-boolean-values","title":"Convert multiple boolean values","text":"<p>If there are a collection of boolean values to convert, the <code>map</code> function can be used to convert them all to 1 or 0.</p> <p>Map this over a collection of values</p> <pre><code>(map {false 0 true 1} [collection-of-boolean-values])\n</code></pre> <p>Example:</p> <pre><code>(map {false 0 true 1} [true false false true true true false false true false true false false true])\n</code></pre>"},{"location":"simple-projects/encode-decode/convert-boolean-values/#how-does-this-work","title":"How does this work?","text":"<p>The <code>map</code> function takes two arguments, a function and a collection.  The <code>map</code> function calls the function given as an argument and calls it with each element of the collection in turn.  The result of each call is remembered by the <code>map</code> function and when the last element of the collection has been used, a new collection of all the results is returned.</p> <p>In the above example, the hash-map {false 0 true 1} acts as a function.</p> <pre><code>({false 0 true 1} true)\n</code></pre> <p>A hash-map acts as a function in that it can return an associated value when given a key as an argument.</p> <p>Calling <code>{false 0 true 1}</code> with <code>true</code> as an argument returns the value <code>1</code>.</p>"},{"location":"simple-projects/encode-decode/rna-dna/","title":"RNA to DNA transcription","text":"<p>Given a DNA strand, return its RNA complement (RNA transcription).</p> <p></p> <p>Both DNA and RNA strands are a sequence of nucleotides.</p> <p>The four nucleotides found in DNA are adenine (A), cytosine (C), guanine (G) and thymine (T).</p> <p>The four nucleotides found in RNA are adenine (A), cytosine (C), guanine (G) and uracil (U).</p> <p>Given a DNA strand, its transcribed RNA strand is formed by replacing each nucleotide with its complement:</p> <pre><code>G -&gt; C\nC -&gt; G\nT -&gt; A\nA -&gt; U\n</code></pre> Inspired by Exercism.io challenge <p>This project was inspired by the RNA Transcription exercise on Exercism.io.  Related exercises include Nucleotide Count and Hamming.</p>"},{"location":"simple-projects/encode-decode/rna-dna/#create-a-project","title":"Create a project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/rna-transcription\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#define-unit-tests","title":"Define unit tests","text":"<p>Open the <code>test/practicalli/rna-transcription.clj</code> and add the following tests</p> <pre><code>(ns practicalli.rna-transcription-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [rna-transcription :as SUT]))\n\n(deftest rna-transcription-test\n  (testing \"transcribe cytosine to guanine\"\n    (is (= \"G\" (SUT/to-rna \"C\"))))\n\n  (testing \"transcribe guanine to cytosine\"\n    (is (= \"C\" (SUT/to-rna \"G\"))))\n\n  (testing \"transcribe adenine to uracil\"\n    (is (= \"U\" (SUT/to-rna \"A\"))))\n\n  (testing \"transcribe thymine to adenine\"\n    (is (= \"A\" (SUT/to-rna \"T\"))))\n\n  (testing \"transcribe all nucleotides\"\n    (is (= \"UGCACCAGAAUU\" (rna-transcription/to-rna \"ACGTGGTCTTAA\"))))\n\n  (testing \"validate dna strands\"\n    (is (thrown? AssertionError (rna-transcription/to-rna \"XCGFGGTDTTAA\")))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#code-the-rna-transcription","title":"Code the RNA transcription","text":"<p>Edit the <code>src/practicalli/rna-transcription.clj</code> file and require the <code>clojure.string</code> library.  The library is part of the Clojure standard library, so does not need to be added as a project dependency.</p> <pre><code>(ns practicalli.rna-transcription\n  (:require [clojure.string :as string]))\n</code></pre> <p>Define a dictionary to convert from DNA nucleotide to its RNA complement</p> <pre><code>(def dictionary-dna-&gt;rna\n  \"Convert DNA to RNA\"\n  {\"G\" \"C\"\n   \"C\" \"G\"\n   \"T\" \"A\"\n   \"A\" \"U\"}\n  )\n</code></pre> <p>Define a function to convert a single DNA nucleotide (one of <code>G</code>, C, T, A) into its RNA complement, using the dictionary.</p> <p>The algorithm is a simple hash-map lookup using the DNA nucleotide as the Key and returning the RNA complement as the value.</p> <pre><code>(defn convert-nucleotide\n  \"Convert a specific nucleotide from a DNA strand,\n  into a nucleotide for an RNA strand\"\n  [dictionary nucleotide]\n  (get dictionary (str nucleotide)))\n</code></pre> <p>Now a single nucleotide can be converted, another function can be defined to convert all DNA nucleotides in a given sequence.</p> <pre><code>(defn to-rna [dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (apply str\n           (map #(convert-nucleotide dictionary-dna-rna %) dna))))\n</code></pre> <p>Although <code>apply str</code> provides the correct answer, it is more idiomatic to use the <code>clojure.string/join</code> function.</p> <pre><code>(defn to-rna [dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (string/join\n           (map #(convert-nucleotide dictionary-dna-rna %) dna))))\n</code></pre> <p>The functions provide the correct answer, however, <code>to-rna</code> is not a pure function as the dictionary is pulled in as a side cause.</p> <p>Update all the tests in <code>test/practicalli/rna-transcription.clj</code> to call <code>SUT/to-rna</code> with a dictionary included in the argument.</p> <pre><code>(ns practicalli.rna-transcription-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [rna-transcription :as SUT]))\n\n(deftest rna-transcription-test\n  (testing \"transcribe cytosine to guanine\"\n    (is (= \"G\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"C\"))))\n\n  (testing \"transcribe guanine to cytosine\"\n    (is (= \"C\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"G\"))))\n\n  (testing \"transcribe adenine to uracil\"\n    (is (= \"U\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"A\"))))\n\n  (testing \"transcribe thymine to adenine\"\n    (is (= \"A\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"T\"))))\n\n  (testing \"transcribe all nucleotides\"\n    (is (= \"UGCACCAGAAUU\" (SUT/to-rna SUT/dictionary-dna-&gt;rna \"ACGTGGTCTTAA\"))))\n\n  (testing \"validate dna strands\"\n    (is (thrown?\n           AssertionError\n           (SUT/to-rna SUT/dictionary-dna-&gt;rna \"XCGFGGTDTTAA\")))))\n</code></pre> <p>Update <code>to-rna</code> to be a pure function by including the dictionary as an argument and also pass the updated tests.</p> <pre><code>(defn to-rna [dictionary dna-sequence]\n  (if (clojure.string/includes? dna-sequence \"X\")\n    (throw (AssertionError.))\n    (string/join\n           (map #(convert-nucleotide dictionary %) dna))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#idiomatic-improvements","title":"Idiomatic improvements","text":"<p>The <code>to-rna</code> function is not pure, as it relies on a shared value in the namespace, the <code>dictionary-dna-rna</code> transcription map.</p> <p>Passing <code>dictionary-dna-rna</code> as an argument to the <code>to-rna</code> function as well as the dna sequence would make <code>to-rna</code> a pure function.  It would also allow use of a range of transcription maps.</p> <pre><code>(defn to-rna\n  \"Transcribe each nucleotide from a DNA strand into its RNA complement\n  Arguments: string representing DNA strand\n  Return: string representing RNA strand\"\n  [transcription dna]\n  (string/join\n    (map #(or (transcription %)\n              (throw (AssertionError. \"Unknown nucleotide\")))\n         dna )))\n</code></pre> <p>The change to the <code>to-rna</code> function will break all the tests.</p> <p>Updated unit tests that call <code>to-rna</code> with both arguments</p> <pre><code>(ns rna-transcription-pure-test\n  (:require [clojure.test :refer [deftest is]]\n            [rna-transcription-pure :as SUT]\n            [rna-transcription :as data]))\n\n(deftest transcribes-cytosine-to-guanine\n  (is (= \"G\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"C\"))))\n\n(deftest transcribes-guanine-to-cytosine\n  (is (= \"C\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"G\"))))\n\n(deftest transcribes-adenine-to-uracil\n  (is (= \"U\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"A\"))))\n\n(deftest it-transcribes-thymine-to-adenine\n  (is (= \"A\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"T\"))))\n\n(deftest it-transcribes-all-nucleotides\n  (is (= \"UGCACCAGAAUU\" (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"ACGTGGTCTTAA\"))))\n\n(deftest it-validates-dna-strands\n  (is (thrown? AssertionError (SUT/dna-&gt;rna data/dna-nucleotide-&gt;rna-nucleotide \"XCGFGGTDTTAA\"))))\n</code></pre>"},{"location":"simple-projects/encode-decode/rna-dna/#hintexercisim-project-and-the-pure-function","title":"Hint::Exercisim project and the pure function","text":"<p>If you wish to keep the Exercisim project passing, then add a new namespace to the project by create a new file called <code>rna-transcript-pure.clj</code>.  Add the new design of the <code>to-rna</code> function to that namespace.  Copy the tests into a new namespace by creating a file called <code>rna-transcription-pure.clj</code> and update the tests to use two arguments when calling <code>to-rna</code></p>"},{"location":"simple-projects/encode-decode/rna-dna/#summary","title":"Summary","text":"<p>This exercise has covered the concept of using a Clojure hash-map structure as a dictionary lookup.</p>"},{"location":"simple-projects/mutating-state/","title":"Mutating State in a Controlled way","text":"<p>Mutating state should be used carefully and sparingly in Clojure (and all other programming languages).</p> <p><code>atom</code> is a mutable container that can manage any value. The atom ensures that only one call at a time can affect the value it manages.  This is part of the software transactions memory system in Clojure.</p> <p>As the atom is mutable in that the value it manages can be changed, however, this must be done with special commands (swap!, reset!, compare-and-set!, swap-vals!).</p> <p>Even though the atom is mutable, the values it manages are not.  They are normal immutable (unchangeable) Clojure values.</p> <p><code>ref</code> is similar to <code>atom</code> and can manage transactions, ensuring that all changes happen or no changes happen.</p> Project Topics Overview Mutants assemble atom swap! reset! Using an atom to manage state changes Undo/Redo atom add-watch Traversing the history of an atom Poker game atom swap! reset! ref Simple transaction management using atom and ref in a card game, using constraints on an atom"},{"location":"simple-projects/mutating-state/#references","title":"References","text":"<ul> <li>Atoms - clojure.org</li> <li>Refs and Transactions - clojure.org</li> <li>Agents - clojure.org</li> </ul>"},{"location":"simple-projects/mutating-state/mutants-assemble/","title":"Mutants Assemble","text":"<p>In this section you will apply changes to values, how to define your own simple functions.</p> <p>We will also introduce the following functions for the first time:</p> function Description <code>atom</code> create an anonymous function, one without a name <code>deref</code>, <code>@</code> assign a name to a function"},{"location":"simple-projects/mutating-state/mutants-assemble/#create-a-new-clojure-project","title":"Create a new Clojure project","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/mutants-assemble\n</code></pre> <p>Open the <code>src/practicalli/mutants_assemble.clj</code> file in a Clojure aware editor and start the REPL.</p>"},{"location":"simple-projects/mutating-state/mutants-assemble/#define-an-atom","title":"Define an atom","text":"<p>Use the <code>def</code> function to bind a name to an atom.</p> <p>The atom wraps data, initially an empty vector.</p> <pre><code>(def mutants (atom []))\n</code></pre> <p>The vector remains an immutable value, even though it is contained within a mutable atom container</p> <p>Define a function using <code>defn</code> which takes a mutant as an argument and updates the value managed by the atom.  The reference to the atom is also an argument, making this a pure function and more generic as any given atom can be updated with this function.</p> <pre><code>(defn add-mutant [mutants mutant]\n  (swap! mutants conj mutant))\n</code></pre> <p><code>swap!</code> uses a function to create a new value for the atom to manage.  In this case the <code>conj</code> function is used to join the value of mutant with the existing mutants atom value, creating a new vector.</p> <p><code>swap!</code> is a macro so the syntax is a little different. Essentially this is the same as an expression <code>(conj mutants mutant)</code>, with the value this returns swapped into the atom.</p> <p>Call the function with the <code>mutants</code> atom and a mutant to add, which is a string containing the name of a mutant character.</p> <pre><code>(add-mutant mutants \"Black Widow\")\n</code></pre> <p>The value the atom is managing has been swapped for a new value.  The original value was not modified (vectors are immutable) so the atom now points to a new value, a vector containing a string.</p>"},{"location":"simple-projects/mutating-state/mutants-assemble/#viewing-the-value-managed-by-the-atom","title":"Viewing the value managed by the atom","text":"<p>Use the <code>deref</code> function to see the value the atom is managing.</p> <pre><code>(deref mutants)\n</code></pre> <p>It is idiomatic to use <code>@</code> which is a syntax alias for the <code>deref</code> function, rather than explicitly using <code>deref</code>.</p> <pre><code>@mutants\n</code></pre>"},{"location":"simple-projects/mutating-state/mutants-assemble/#reset-the-atom-value","title":"Reset the atom value","text":"<p><code>reset!</code> will change the value managed by the atom by providing the new value.  This is simpler than using <code>swap!</code> as it does not use the existing value in the atom.</p> <pre><code>(reset! mutants [])\n</code></pre> <p>Now all the mutants are gone (and we can start looking for new ones to add).</p>"},{"location":"simple-projects/tdd-kata/","title":"Kata challenges","text":"<p>A kata is a small challenge that you attempt to solve in different ways, so experiment with your solutions to these challenges.</p> <p>Kata are often coupled with Test Driven Development approach.</p> Project Topics Overview Recent song-list TDD Keep a list of recent songs played, without duplicates Salary Slip Generator TDD Generate play slips for an employee <p>Code Kata Website</p> <p></p>"},{"location":"simple-projects/tdd-kata/recent-song-list/","title":"TDD Kata Recent Song-list","text":"<p>Create a recent song list to hold a unique set of songs that have been played.</p> <p>The most recently played song is at the start of the list, the least recently played song is the last in the list.</p> <ul> <li>A recently-used-list is initially empty.</li> <li>Songs in the list are unique, so repeatedly played songs should only appear once in the list</li> <li>Songs can be looked up by index, which counts from zero.</li> <li>The song list can be transitory (starting from empty each time) or persistent within a REPL session (examples use a transitory approach)</li> </ul> <p>Optional extras:</p> <ul> <li>Empty song names are not allowed.</li> <li>Add a limit to the number of songs the list contains, with the least recently added items dropped when that limit is reached.</li> </ul>"},{"location":"simple-projects/tdd-kata/recent-song-list/#create-project","title":"Create Project","text":"<p>Create a new project using clj-new</p> <pre><code>clojure -T:project/create practicalli/song-list\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#run-repl","title":"Run REPL","text":"<p>Start a Clojure REPL via a Clojure editor or via the command line from the root of the project directory</p> <p>Start rich terminal UI Clojure REPL</p> <pre><code>clojure -M:repl/rebel\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#unit-tests","title":"Unit Tests","text":"<p><code>clojure.test</code> library is part of Clojure standard library and is the most common way to write unit tests in Clojure</p> <p>Open <code>test/playground/song_list_test.clj</code> file in your editor and update the namespace definition to include <code>clojure.test</code></p> <p>Require clojure.test namespace</p> test/playground/song_list_test.clj<pre><code>(ns practicalli.song-list-test\n  (:require [clojure.test :refer [deftest is testing]]\n            [playground.song-list :as song-list]))\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#run-tests","title":"Run Tests","text":"<p>Evaluate the <code>practicalli.song-list</code> and <code>practicalli.song-list-test</code> namespaces to load their code into the REPL</p> <p>Call the <code>run-tests</code> function in the REPL to get a report back on all of the tests in our current namespace (<code>song-list</code>)</p> Kaocha test runnerclojure.test runner <p> Practicall Clojure CLI Config provides the <code>:test/run</code> alias to run the Kaocha test runner.</p> <p>Kaocha test runner</p> <p>Open a command line in the root directory of the project and run the following command. <pre><code>clojure -X:test/run\n</code></pre></p> <p>Kaocha runs all the tests, stopping should a test fail.</p> <p>Kaocha test runner with file watch</p> <p>Use the <code>:test/watch</code> alias to automatically run tests when ever a file is saved <pre><code>clojure -X:test/run\n</code></pre></p> <p>Evaluate the project code and evaluate the <code>run-tests</code> function from <code>clojure.test</code> from within the REPL</p> <p>clojure.test runner</p> <pre><code>(run-tests)\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-list-exists","title":"Test song-list exists","text":"<p>Write a test to see if a recent song list exists.</p> <p>This is an opportunity to think about what kind of data structure you want to use to hold your recent song list.</p> <p>Try write the code first and then check that code with the examples provided (click to expand each code example box)</p> Test song-list exists <p>A simple test that checks for a <code>recent-songs</code> list src/playground/song_list.clj<pre><code>(deftest song-list-exists-test\n  (testing \"Does a recent song list exist\"\n    (is (vector? song-list/recent-songs))))\n</code></pre> <code>recent-songs</code> should be defined in <code>src/playground/recent-song-list.clj</code> before running the test, otherwise a compilation error will be returned.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#define-a-recent-song-list","title":"Define a recent song list","text":"<p>Edit <code>src/playground/song_list.clj</code> and define a name for the collection of recent songs</p> <p>Use an empty collection to start with.  Which collection type will you use though (hash-map <code>{}</code>, list <code>()</code>, set <code>#{}</code>, vector <code>[]</code>)?</p> recent-songs collection <p>Define a recent-song name for an empty vector src/playground/song_list.clj<pre><code>(def recent-songs [])\n</code></pre></p> Test First Approach <p>For a strict test first approach, a <code>recent-songs</code> name (symbol) would be defined that returns <code>false</code> or a falsy value, e.g. <code>nil</code></p> <p>A name (symbol) must be defined for use in the test so that the Clojure code can compile</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-list-is-empty","title":"Test song-list is empty","text":"<p>The recent song list should be empty to start with.</p> Check song list is empty <p>A simple test that compares an empty vector with the value of <code>recent-songs</code> src/playground/song_list.clj<pre><code>(deftest song-list-empty-test\n  (testing \"Is song list empty if we haven't added any songs\"\n    (is\n     (= [] song-list/recent-songs))))\n</code></pre></p> <p>Here is the same test using the <code>empty?</code> function instead of the <code>=</code> function.</p> <p>src/playground/song_list.clj<pre><code>(deftest song-list-empty-test\n  (testing \"Is song list empty if we haven't added any songs\"\n    (is\n     (empty? song-list/recent-songs))))\n</code></pre> Either of these tests could replace the test that the song list exists, as these tests would fail if the song list did not exist.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-adding-a-song-to-the-list","title":"Test adding a song to the list","text":"<p>Add a song to the collection, for example <code>Tubular Bells - Mike Oldfield</code></p> Test adding a song to the list test/playground/song_list_test.clj<pre><code>(deftest add-songs-test\n\n  (testing \"add song returns a song list with entries\"\n    (is\n     (not (empty?\n           (add-song \"Barry Manilow - Love on the rocks\" song-list/recent-songs)))))\n\n  (testing \"add multiple song returns a song list with entries\"\n    (is\n     (not (empty?\n           (-&gt;&gt; song-list/recent-songs\n             (add-song \"Mike Oldfield - Tubular Bells Part 1\")\n             (add-song \"Barry Manilow - Love on the rocks\")\n             (add-song \"Phil Colins - Sususudio\" )))))))\n</code></pre> <p>Other songs are avialbe and Practicalli makes no recommendation as to what songs should be used or listened too.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#function-to-add-song","title":"Function to add song","text":"<p>Create a function to add a song to the start of the song list.</p> Function to add song to list <p>The <code>add-song</code> function takes the name of a song and the song list to which it will be added.</p> <p>A Thread-last macro <code>-&gt;&gt;</code> is used to pass the song list over two functions.</p> <p>The <code>song-list</code> is first passed to the <code>remove</code> expression as its last argument.  This expression will remove any occurrence of the new song we want to add from the <code>song-list</code>.</p> <p>The results of the <code>remove</code> expression are then passed to the <code>cons</code> expression as its last argument.  The <code>cons</code> expression simply adds the new song to the start of the list, making it the most recent song.</p> src/playground/song_list.clj<pre><code>(def recent-songs [])\n\n(defn add-song [song song-list]\n  (cons song song-list))\n</code></pre> <p><code>recent-songs</code> is passed into the <code>add-song</code> function as an argument, <code>song-list</code> to keep the design of <code>add-song</code> function pure (no side-effects).  This design also provides greater scope to using the <code>add-song</code> function, as any song list can be added to, rather than hard-coding <code>recent-songs</code> list.</p>"},{"location":"simple-projects/tdd-kata/recent-song-list/#test-song-added-to-top-of-list","title":"Test song added to top of list","text":"<p>As the song list shows recently played songs, new songs added should be at the top of the list.</p> <p>The list should not contain duplicate entries for a song.</p> Test songs added to top of list test/playground/song_list_test.clj<pre><code>(deftest recently-added-song-first-test\n\n  (testing \"most recent song should be first in the list when empty list\"\n    (is (=\n         (first (add-song \"Daft Punk - Get Lucky\" recent-songs))\n         \"Daft Punk - Get Lucky\")))\n\n  (testing \"most recent song should be first in list when adding multiple songs\"\n    (is (=\n         (first\n          (-&gt;&gt; recent-songs\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\")))\n\n  (testing \"most recent song should be first in list when adding a repeated song\"\n    (is (=\n         (first\n          (-&gt;&gt; recent-songs\n               (add-song \"Pharrell Williams - Happy\")\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\")))\n\n  (testing \"most recent song should be first in list when adding a repeated song\"\n    (is (not=\n         (last\n          (-&gt;&gt; recent-songs\n               (add-song \"Pharrell Williams - Happy\")\n               (add-song \"Daft Punk - Get Lucky\")\n               (add-song \"Pharrell Williams - Happy\")))\n         \"Pharrell Williams - Happy\"))))\n</code></pre>"},{"location":"simple-projects/tdd-kata/recent-song-list/#add-song-to-start-of-list","title":"Add song to start of list","text":"<p>Create a function to add a song to the start of the song list.</p> Function to add song to list <p>The <code>add-song</code> function takes the name of a song and the song list to which it will be added.</p> <p>A Thread-last macro <code>-&gt;&gt;</code> is used to pass the song list over two functions.</p> <p>The <code>song-list</code> is first passed to the <code>remove</code> expression as its last argument.  This expression will remove any occurrence of the new song we want to add from the <code>song-list</code>.</p> <p>The results of the <code>remove</code> expression are then passed to the <code>cons</code> expression as its last argument.  The <code>cons</code> expression simply adds the new song to the start of the list, making it the most recent song.</p> src/playground/song_list.clj<pre><code>(def recent-songs [])\n\n(defn add-song [song song-list]\n  (-&gt;&gt; song-list\n       (remove #(= song %))\n       (cons song)))\n</code></pre> <p><code>recent-songs</code> is passed into the <code>add-song</code> function as an argument, <code>song-list</code> to keep the design of <code>add-song</code> function pure (no side-effects).  This design also provides greater scope to using the <code>add-song</code> function, as any song list can be added to, rather than hard-coding <code>recent-songs</code> list.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/","title":"Salary Slip Kata","text":"<p> Pracitcalli Clojure CLI Config provides the <code>:project/create</code> alias to create projects using deps-new project.</p> <pre><code>clojure -T:project/create :template app :name practicalli/salary-calculator\n</code></pre>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#problem-description","title":"Problem description","text":"<p>A typical salary slip contains employee details like employee id, employee name and their monthly salary details like their gross salary, national insurance contributions, tax-free allowance, taxable income and tax payable.</p> <p>Salary slips are generated each month for every employee.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#acceptance-criteria","title":"Acceptance criteria","text":"<ul> <li>Salary slip generator should receive an employee with its Employee Id, Employee Name and Annual Gross Salary</li> <li>Salary slip should contain the Employee ID, Employee Name, Gross Salary, National Insurance contributions, Tax-free allowance, Taxable income and Tax payable for the month</li> <li>The entry point should be the following public function API</li> </ul> <pre><code>(defn salary-slip-generator\n  \"\"\n  [employee]\n  ,,,)\n</code></pre>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iterations","title":"Iterations","text":"<p>Each iteration adds more rules to the calculation. Some iterations also introduce new fields to the salary slip.</p> <p>In a given iteration, all the salary slips contain the same number fields for each employee (if a tax or contribution does not apply for a given employee, just put \u00a30.00).</p> <p>This means that for each iteration you will need to add fields to the <code>SalarySlip</code> class. In the first iteration, <code>SalarySlip</code> only contains the Employee ID, Employee Name and Monthly Gross Salary.</p>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-1-for-an-annual-salary-of-500000","title":"Iteration 1: for an annual salary of \u00a35,000.00","text":"<p>This is the most basic case.</p> <ul> <li>Given I have an employee John J Doe with an annual gross salary of \u00a35,000.00</li> <li>When I generate a monthly salary slip for the employee</li> <li>Then the monthly salary slip should contain the below<pre><code>   Employee ID: 12345\n   Employee Name: John J Doe\n   Gross Salary: \u00a3416.67\n</code></pre> </li> </ul> <p>Calculation rules:</p> <ul> <li>Monthly Gross Salary: The monthly gross salary is the employee's annual gross salary divided by 12</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-2-for-an-annual-gross-salary-of-906000","title":"Iteration 2: for an annual gross salary of \u00a39,060.00","text":"<p>Here we introduce the National Insurance contribution</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a3755.00\n       National Insurance contributions: \u00a310.00\n</code></pre> <p>Calculation rules:</p> <ul> <li>National Insurance contributions: Any amount of money earned above a gross annual salary of \u00a38,060.00 is subject to a National Insurance contribution of 12%</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-3-for-an-annual-gross-salary-of-1200000","title":"Iteration 3: for an annual gross salary of \u00a312,000.00","text":"<p>This employee also needs to pay taxes</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a31,000.00\n       National Insurance contributions: \u00a339.40\n       Tax-free allowance: \u00a3916.67\n       Taxable income: \u00a383.33\n       Tax Payable: \u00a316.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Taxable income: Any amount of money earned above a gross annual salary of \u00a311,000.00 is taxed at 20%</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-4-for-an-annual-gross-salary-of-4500000","title":"Iteration 4: for an annual gross salary of \u00a345,000.00","text":"<p>This employee pays a higher band of National Insurance and Income Tax.</p> <p>The monthly salary slip should contain the below:</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a33,750.00\n       National Insurance contributions: \u00a3352.73\n       Tax-free allowance: \u00a3916.67\n       Taxable income: \u00a32,833.33\n       Tax Payable: \u00a3600.00\n</code></pre> <p>Calculation rules:</p> <ul> <li>Taxable income (higher rate): Any amount of money earned above a gross annual salary of \u00a343,000.00 is taxed at 40%</li> <li>National Insurance (higher contributions): Any amount of money earned above a gross annual salary of \u00a343,000.00 is only subject to a 2% NI contribution</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-5-for-annual-gross-salaries-of-10100000-11100000-12200000-and-15000000","title":"Iteration 5: for annual gross salaries of \u00a3101,000.00; \u00a3111,000.00; \u00a3122,000.00 and \u00a3150,000.00","text":"<p>For high earners, the tax-free allowance decreases.</p> <p>The monthly salary slips should contain the below (respectively):</p> <pre><code>       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a38,416.67\n       National Insurance contributions: \u00a3446.07\n       Tax-free allowance: \u00a3875.00\n       Taxable income: \u00a37,541.67\n       Tax Payable: \u00a32,483.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a39,250.00\n       National Insurance contributions: \u00a3462.73\n       Tax-free allowance: \u00a3458.33\n       Taxable income: \u00a38,791.67\n       Tax Payable: \u00a32,983.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a310,166.67\n       National Insurance contributions: \u00a3481.07\n       Tax-free allowance: \u00a30.00\n       Taxable income: \u00a310,166.67\n       Tax Payable: \u00a33,533.33\n\n\n       Employee ID: 12345\n       Employee Name: John J Doe\n       Gross Salary: \u00a312,500.00\n       National Insurance contributions: \u00a3527.73\n       Tax-free allowance: \u00a30.00\n       Taxable income: \u00a312,500.00\n       Tax Payable: \u00a34,466.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Tax-free allowance: When the Annual Gross Salary exceeds \u00a3100,000.00, the tax-free allowance starts decreasing. It decreases by \u00a31 for every \u00a32 earned over \u00a3100,000.00. And this excess is taxed at the Higher rate tax.</li> </ul>"},{"location":"simple-projects/tdd-kata/salary-slip-generator/#iteration-6-for-an-annual-gross-salary-of-16000000","title":"Iteration 6: for an annual gross salary of \u00a3160,000.00","text":"<p>The employee goes into the additional rate band.</p> <p>The monthly salary slip should contain the below:</p> <pre><code>      Employee ID: 12345\n      Employee Name: John J Doe\n      Gross Salary: \u00a313,333.33\n      National Insurance contributions: \u00a3544.40\n      Tax-free allowance: \u00a30.00\n      Taxable income: \u00a313,333.33\n      Tax Payable: \u00a34,841.67\n</code></pre> <p>Calculation rules:</p> <ul> <li>Income tax (additional rate band) : Any amount of money earned above a gross annual salary of \u00a3150,000.00 is taxed at 45%</li> </ul> Practicalli Salary Slip Kata <p>Salary slip kata - Devoxx 2019</p> <pre><code>(ns salary-slip-kata.core\n  \"Developer Anarchy by Fred George\n   - made devs write the same solution in different languages\n   -- helps devs master the business domain\n   -- helps devs master technology domain\")\n\n(defn- national-insurance-contribution\n  \"Calculate the national insurance contribution due for a given annual salary.\n\n  ---------------------+-------------------------+--------\n  Band                 | NI deductible income    | NI Rate\n  ---------------------+-------------------------+--------\n  No contributions     | Up to \u00a38,060.00         |    0%\n  Basic contributions  | \u00a38,060.00 to \u00a343,000.00 |   12%\n  Higher contributions | over \u00a343,000.00         |    2%\n  ---------------------+-------------------------+-------- \"\n\n  [annual-gross-salary]\n  ;; add a cond statement to return the calculate the value with respect to the band.\n  (* annual-gross-salary 0.12))\n\n\n;; taxable income\n;; ---------------------+---------------------------+---------\n;; Band                 | Taxable income            | Tax rate\n;; ---------------------+---------------------------+---------\n;; Personal Allowance*  | Up to \u00a311,000.00          |    0%\n;; Basic rate           | \u00a311,000.00 to \u00a343,000.00  |   20%\n;; Higher rate          | \u00a343,000.00 to \u00a3150,000.00 |   40%\n;; Additional rate      | over \u00a3150,000.00          |   45%\n;; ---------------------+---------------------------+---------\n\n\n(defn salary-slip\n  \"Creates a salary slip for a person\n\n  Specifically for employee of 24K annual salary\"\n\n  [{:keys [employee-id\n           employee-name\n           annual-gross-salary]}]\n  (let [tax-free-allowance 11000\n        taxable-income     (- annual-gross-salary\n                              tax-free-allowance)]\n    {:employee-id        employee-id\n     :employee-name      employee-name\n     :gross-salary       (/ annual-gross-salary 12)\n     :national-insurance (national-insurance-contribution annual-gross-salary)\n     :tax-free-allowance tax-free-allowance\n     :taxable-income     taxable-income\n     :tax-payable        (* taxable-income 0.20)}))\n</code></pre>"},{"location":"testing/","title":"Testing in Clojure","text":"<p>Testing is supported in Clojure with a range of testing libraries and test runners.</p>"},{"location":"testing/#unit-test","title":"Unit Test","text":"<p>The unit of test in Clojure is the function, so functions are defined that test other functions.</p> <p>clojure.test namespace is part of the Clojure standard library and provides assertion based testing and functions to run tests.</p> <p>Practicalli Unit Testing Guide Using Test Runners</p>"},{"location":"testing/#generative-testing","title":"Generative testing","text":"<p>Define specifications for values to confirm information coming into and leaving a Clojure service are of the correct form.</p> <p>Generate test data from value specifications to verify the behaviour of functions, creating diverse sets of data for extensive testing.</p> <p>Define specifications for functions to validate the correct form of values are passed and returned from a function.</p> <p>Define value and function specifications with Cloure Spec Generative Testing with Clojure Spec</p>"},{"location":"testing/#performance-testing","title":"Performance testing","text":"<p>Test individual expressions through to application and load testing one or more services.</p> <ul> <li>time - simple results of evaluating an expression</li> <li>criterion - a realistic measure of performance for clojure expressions</li> <li>Gatling - open source &amp; commercial load test tool for web applications</li> <li>clj-gatling - wrapper around Gatling which enables tests to be expressed in Clojure.</li> </ul>"},{"location":"testing/#behaviour-driven-development-frameworks","title":"Behaviour Driven Development frameworks","text":"<p>Although not widely used in the Clojure community, there are several approaches to develop and test software using Behaviour Driven Development.</p> <p>BDD: Given, When, Then and scenario approach to outside in software testing</p> <ul> <li>Scenari - executable specification / BDD in Clojure</li> <li>kaocha-cucumber - support for Cucumber tests in the gerkin format</li> <li>speclj - TDD/BDD framework for Clojure and ClojureScript based on RSpec.</li> </ul> <p>Alternative BDD libraries are discussed at https://github.com/gphilipp/bdd-guide-clojure</p>"},{"location":"testing/#articles-on-testing-in-clojure","title":"Articles on testing in Clojure","text":"<ul> <li>Clojure test runner of my dreams</li> <li>Example based unit testing in Clojure</li> <li>TDD in Clojure at Funding Circle</li> <li>Bolth - a more humane test runner</li> <li>Announcing kaocha a new and improved clojure test runner</li> <li>Scenarios as code - Clojure Remote presentation</li> <li>Load testing with Gatling and Clojure - JUXT.pro</li> </ul>"},{"location":"testing/clojure-test/","title":"Unit Testing with <code>clojure.test</code>","text":"<p><code>clojure.test</code> is a test library that is already part of Clojure and test package hierarchy is typically created (e.g. when generating Clojure projects with Leiningen).</p> <p>As with other unit testing libraries you use <code>clojure.test</code> to write test.  These tests are defined as functions that contain one or more assertions.</p> <p>As a general guideline, a Clojure test function should test a specific Clojure function.</p>"},{"location":"testing/clojure-test/#hintwhat-to-test","title":"Hint::What to test","text":"<p>Define a <code>deftest</code> for every public functions within a namespace, so the contract / api for each namespace is testable and will highlight obvious regressions. The <code>testing</code> function can be used to group assertions for a particular <code>deftest</code>, so different aspects of the tests can be grouped together.</p> <p>Test reports contain only the names of the <code>deftest</code> functions, as there are no names with <code>testing</code></p> <p><code>clojure.spec</code> provides another way to define a contract around your functions and data structures.  It also includes generative testing approach to broaden the test data used to test your functions.</p>"},{"location":"testing/clojure-test/#test-namespaces","title":"Test namespaces","text":"<p><code>clojure.test</code> needs to be included in the namespace in order to use the functions that namespace provides.</p> <p>The recommended syntax is to <code>:refer</code> the specific functions which makes those functions available as if they were defined in the current namespace.</p> <p>The namespace that is under test also needs to be included and and its recommended that you use the alias <code>SUT</code> for system under test.  The test namespace matches the namespace you are testing, with the addition of <code>-test</code> to the name.</p> <pre><code>(ns my-clojure-app.core-test\n  (:require [clojure.test :refer [deftest deftest- testing is]]\n            [my-clojure-app.core :as SUT ]))\n</code></pre>"},{"location":"testing/clojure-test/#writing-an-assertion","title":"Writing an assertion","text":"<p>An assertion is where you compare an expected result with the result of calling a function.  If the assertion is true, then then it is a pass.  If the assertion is false, then its a fail.</p> <p>The form of an assertion takes a form <code>(is (comparator expected-value function-call))</code></p> <p>Some simple examples include</p> <pre><code>(is (= 42 (* 6 7)))\n\n(is (not= 24 (* 6 7)))\n</code></pre>"},{"location":"testing/clojure-test/#defining-a-test","title":"Defining a test","text":"<p><code>deftest</code> is used to define a function that will test a similarly named function from the <code>src</code> tree.  The test function name should match the function it is testing with <code>-test</code> added to the end.</p> <p><code>testing</code> function allows you to group one or more assertions</p> <p><code>is</code> defines an assertion</p> <pre><code>(deftest adder-test\n  (testing \"Using a range of numbers to test the adder\"\n    #_(is (= 0 1))\n    (is (= (+ 1 2) (adder 1 2)) \"Adding 1 and 2\")\n    (is (= (+ 1 -2) (adder 1 -2)) \"Adding 1 and -2\")\n    #_(is (not (= (+ 1 2)) (adder \"a\" \"b\")) \"Adding strings as negative test\")\n    (is (false? (= 0 1)) \"A simple failing test\")\n    (is (false? (= 0 (adder 3 4))) \"Purposefully using failing data\")))\n</code></pre>"},{"location":"testing/integration-testing/","title":"Integration Testing","text":"<p>See the continuous integration section</p>"},{"location":"testing/test-runners/","title":"Test Runners","text":"<p>A test runner is used to run one or more unit tests in a project and report the results.  When there are failing tests, a test runners show details of how the failing test, showing actual and expected values.</p> <p>Test runners may support specification testing with clojure.spec, checking data and functions conform to their specifications.</p> <p>Test runners are called from either a Clojure editor, as a command line tool or within a continuous integration workflow.</p> <p>Regularly run tests in a project to ensure implementations and design decisions made so far have not regressed.</p> Test runner Type Summary cognitect-labs test runner clj Simple test runner cljs-test-runner cljs Run all ClojureScript tests with one simple command. Kaocha clj, cljs Full featured test runner CIDER test runner clj CIDER built in test runner <p> CIDER test runner is ideal if using Emacs for Clojure development, as its build into CIDER.</p> <p>Practicalli Recommends Kaocha test runner</p> <p>Kaocha is a very feature rich test runner for Clojure and ClojureScript, BDD style cucumber tests, coverage and junit style reporting.</p> <p> Practicalli Clojure CLI Config - test runner aliases</p> <p> Practicalli Clojure CLI Config contains several aliases for test runners</p> <ul> <li><code>:test/env</code> adds the <code>test</code> directory to the class path and <code>org.clojure/test.check</code> library</li> <li><code>clojure -X:test/run</code> run Kaocha test runner</li> <li><code>clojure -X:test/watch</code> run Kaocha test runner in watch mode, running on file changes</li> <li><code>clojure -M:test/cljs</code>  run Kaocha ClojureScript test runner</li> <li><code>clojure -X:test/cognitect</code> simple to use Cognitect test runner</li> <li><code>:lib/kaocha</code> adds Kaocha as a library to the class path, enabling Kaocha to run from an editor, e.g. Emacs Cider with Kaocha test runner</li> </ul> <p>Practicalli REPL Reloaded aliases <code>:repl/reloaded</code> &amp; <code>:dev/reloaded</code> also support Kaocha test runner</p>"},{"location":"testing/test-runners/aero/","title":"Aero","text":"<p>juxt/aero is used to read the kaocha configuration, so reader literals such as #env, #merge, #ref, and #include can be used.</p> <p>Set up profiles for different stages of the development workflow, dev, test, prod, etc.  Each profile has a different configuration making it very easy to switch</p> <pre><code>{:port 8000\n :database #profile {:prod \"datomic:dev://localhost:4334/my-prod-db2\"\n                     :test \"datomic:dev://localhost:4334/my-test-db\"\n                     :default \"datomic:dev://localhost:4334/my-db\"}\n :known-users [{:name \"Alice\"} {:name \"Betty\"}]}\n</code></pre> <p>Then in application startup function or a component lifecycle library (mount, component, integrant) read in a specific profile</p> <pre><code>(aero.core/read-config \"config.edn\" {:profile :prod})\n</code></pre>"},{"location":"testing/test-runners/congnitect-labs-test-runner/","title":"Cognitect Labs Test Runner","text":"<p>Cognitect Labs test-runner is a test runner for Clojure projects defined with <code>deps.edn</code> and using <code>clojure.test</code> library which is part of the Clojure standard library.</p> <p>test-runner aims to provide a standard way to discover and run unit and property-based tests, in a simple to use and lightweight tool.</p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#add-test-runner","title":"Add test-runner","text":"<p>Make test-runner available to all projects by adding it to <code>~/.clojure/deps.edn</code>.  Or add test-runner to specific projects by adding an alias to the project <code>deps.edn</code> file.  Include <code>:extra-paths</code> configuration to include the standard <code>test</code> directory so that the runner has access to the test code.</p> Practicalli Clojure CLI ConfigAlias Definition <p>  Practicalli Clojure CLI Config provides aliases for test runner tools, including <code>:test/congnitect</code> for running Cognitect Labs test runner</p> <p>Add an alias to run Cognitect Labs test runner, either in the project or user <code>deps.edn</code> configuration file. ```clojure   :test/cognitect   {:extra-paths [\"test\"]    :extra-deps  {com.cognitect/test-runner                  {:git/url \"https://github.com/cognitect-labs/test-runner.git\"                   :sha     \"f7ef16dc3b8332b0d77bc0274578ad5270fbfedd\"}}    :main-opts   [\"-m\" \"cognitect.test-runner\"]}</p> <p>```</p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#run-test-runner","title":"Run test runner","text":"<p>Run the Cognitect Labs test runner via the command line</p> <pre><code>clojure -M:test/cognitect\n</code></pre> <p>The <code>cognitect.test-runner/-main</code> function is called which scans the <code>test</code> directory of the current project tests defined using <code>clojure.test</code>,  running all tests found.</p> <p>A summary is returned with the results of running the tests.</p> <p></p>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#command-line-options","title":"Command line options","text":"Flag Description -d, --dir DIRNAME Name of the directory containing tests. Defaults to \"test\". -n, --namespace SYMBOL Symbol indicating a specific namespace to test. -r, --namespace-regex REGEX Regex for namespaces to test. Defaults to #\".*-test$\"  (i.e, only namespaces ending in '-test' are evaluated) -v, --var SYMBOL Symbol indicating the fully qualified name of a specific test. -i, --include KEYWORD Run only tests that have this metadata keyword. -e, --exclude KEYWORD Exclude tests with this metadata keyword. -H, --test-help Display this help message <p>Options can be used multiple times in one command, for a logical OR effect. For example, the following command runs all tests in the <code>practicalli.data.survey</code> and <code>practicalli.services.survey-report</code> namespaces that are found in the <code>src</code> and <code>test</code> directories</p> <pre><code>clojure -M:test/cognitect -d test -d src -n practicalli.data.survey -n practicalli.services.survey-report\n</code></pre>"},{"location":"testing/test-runners/congnitect-labs-test-runner/#test-selectors","title":"Test Selectors","text":"<p>Selectively running tests by including and excluding test categories, from the meta-data added to test definitions, i.e. <code>deftest</code>.</p> <pre><code>(deftest ^:integration test-live-system\n  (is (= 200 (:status (http/get \"http://example.com\")))))\n</code></pre> <p>Use the <code>--include</code> flag with the test runner to specify specific categories of tests</p> <pre><code>clojure -M:test-runner-cognitect --include :integration\n</code></pre> <p>The <code>--include</code> flag can be used multiple times, defining a test category with each include.</p> <pre><code>clojure -M:test-runner-cognitect --include :integration --include :persistence\n</code></pre> <p>Clojure Unit Test - categories example integration and develop tests</p> <p><code>--exclude</code> flag runs all tests except those in the given category</p> <pre><code>clojure -M:test/cognitect --exclude :integration\n</code></pre> <p>Exclusions take priority over inclusions if both flags are included.</p>"},{"location":"testing/test-runners/example-projects/","title":"Example projects","text":"<ul> <li>TDD Kata: Recent Song-list - simple tests examples</li> <li>Codewars: Rock Paper Scissors (lizard spock) solution - <code>and</code> examples</li> <li>practicalli/numbers-to-words - overly verbose example, ripe for refactor</li> <li>practicalli/codewars-guides - deps.edn projects</li> <li>practicalli/exercism-clojure-guides - Leiningen projects</li> </ul>"},{"location":"testing/test-runners/example-projects/#sean-corfield-user-manager","title":"Sean Corfield - user manager","text":"<p>User manager has unit tests that also include an embedded database.  Tests can run with the Cognitect Labs test runner.</p> <p><code>:test</code> alias includes the test path and a dependency for the H2 database</p> <p>Cognitect Labs test runner included in the project <code>deps.edn</code> file as <code>:runner</code></p> <p><code>clojure -M:test:runner</code> will run the Cognitect Labs runner and include the dependency to run the in-memory database used for the tests.</p>"},{"location":"testing/test-runners/example-projects/#using-koacha-with-sean-corfield-user-manager","title":"Using koacha with Sean Corfield user manager","text":"<p>Adding a <code>test.edn</code> file is not sufficient for testing this project with lambdaisland/kaocha, as the H2 dependency is also needed.</p> <p>Create a <code>bin/koacha</code> script and add the extra alias</p> <pre><code>#!/usr/bin/env bash\nclojure -M:test:test-runner-kaocha \"$@\"\n</code></pre>"},{"location":"testing/test-runners/example-projects/#status-monitor","title":"Status Monitor","text":"<p>Status monitor is a Leiningen project.</p> <p>Include a <code>:kaocha</code> profile in the <code>project.clj</code> file, adding the koacha dependency.  The <code>:kaocha</code> alias sets the main namespace and uses the kaocha profile.</p> <pre><code>  {:dev    {:dependencies [[javax.servlet/servlet-api \"2.5\"]\n                           [ring/ring-mock \"0.3.2\"]]}\n   :kaocha {:dependencies [[lambdaisland/kaocha \"1.0.632\"]]}}\n  :aliases {\"kaocha\" [\"with-profile\" \"+kaocha\" \"run\" \"-m\" \"kaocha.runner\"]}\n</code></pre> <p><code>lein kaocha</code> will run all the tests</p>"},{"location":"testing/test-runners/kaocha-test-runner/","title":"LambdaIsland Kaocha Test Runner","text":"<p> lambdaisland/kaocha (cow-cha) is a comprehensive test runner that support unit testing and <code>clojure.spec</code> generative testing.  Clojure and ClojureScript languages are supported.</p> <p>Kaocha is highly configurable via a <code>tests.edn</code> configuration file in the root of the project.</p>"},{"location":"testing/test-runners/kaocha-test-runner/#clojure-cli-config","title":"Clojure CLI Config","text":"Practicalli Clojure CLI ConfigAlias Definition <p>  Practicalli Clojure CLI Config configuration contains aliases to run kaocha test runner, using either the <code>-X</code> or <code>-M</code> execution flag.</p> <ul> <li><code>:test/run</code> - run all tests in the project, stopping on first failing test</li> <li><code>:test/watch</code> - watching for file changes and run all tests in the project, stopping on first failing test</li> <li><code>:test/env</code> - add supporting paths and libraries for testing projects</li> </ul> <p>Each alias includes <code>:extra-paths [\"test\"]</code> to include the <code>test</code> directory on the class path, enabling Koacha test runner to find the unit test code.</p> <p>Define an alias in the project or user <code>deps.edn</code> configuration.</p> <p>For CI services such as CircleCI or GitLabs, add an alias for kaocha to the project <code>deps.edn</code> file.</p> <p>Alias definitions for LambdaIsland/Kaocha test runner</p> <p>Aliases support the <code>-M</code> (clojure.main) and <code>-X</code> (clojure.exec) execution options with Clojure CLI. <pre><code>:test/run\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.77.1236\"}}\n :main-opts   [\"-m\" \"kaocha.runner\"]\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:fail-fast? true\n             :randomize? false}}\n\n;; Kaocha test runner in watch mode\n;; clojure -X:test/watch\n:test/watch\n{:extra-paths [\"test\"]\n :extra-deps {lambdaisland/kaocha {:mvn/version \"1.77.1236\"}}\n :main-opts   [\"-m\" \"kaocha.runner\" \"--watch\" \"--fail-fast\" \"--skip-meta\" \":slow\"]\n :exec-fn kaocha.runner/exec-fn\n :exec-args {:watch? true\n             :randomize? false\n             :fail-fast? true}}\n</code></pre></p> <p>Libraries and directories containing code to support testing projects can be added to the <code>:test/env</code> alias <pre><code>:test/env\n{:extra-paths [\"test\"]\n :extra-deps  {org.clojure/test.check {:mvn/version \"1.1.1\"}}}\n</code></pre></p> <p>Alias definitions should include <code>:extra-paths [\"test\"]</code> to add the <code>test</code> directory on the class path, enabling Koacha test runner to find the unit test code.</p>"},{"location":"testing/test-runners/kaocha-test-runner/#run-kaocha","title":"Run Kaocha","text":"<p>Kaocha can be run via make tasks, Clojure CLI, or by creating a <code>kaocha</code> script.</p> <p>Babashka task runner could also be used to develop tasks to run kaocha</p> MakeClojure CLIKaocha script <p>  Practialli Makefile contains tasks for testing Clojure projects with Kaocha (and many other common Clojure development tasks)</p> Practicalli Makefile targets for unit testing <p>Practicalli Makefile includes the following targets for Kaocha test runner Makefile<pre><code># ------- Testing -------------------- #\n\ntest-config:  ## Run unit tests - stoping on first error\n    $(info --------- Runner Configuration ---------)\n    clojure -M:test/env:test/run --print-config\n\ntest-profile:  ## Profile unit test speed, showing 3 slowest tests\n    $(info --------- Runner Profile Tests ---------)\n    clojure -M:test/env:test/run --plugin  kaocha.plugin/profiling\n\ntest:  ## Run unit tests - stoping on first error\n    $(info --------- Runner for unit tests ---------)\n    clojure -X:test/env:test/run\n\n\ntest-all:  ## Run all unit tests regardless of failing tests\n    $(info --------- Runner for all unit tests ---------)\n    clojure -X:test/env:test/run :fail-fast? false\n\ntest-watch:  ## Run tests when changes saved, stopping test run on first error\n    $(info --------- Watcher for unit tests ---------)\n    clojure -X:test/env:test/run :watch? true\n\ntest-watch-all:  ## Run all tests when changes saved, regardless of failing tests\n    $(info --------- Watcher for unit tests ---------)\n    clojure -X:test/env:test/run :fail-fast? false :watch? true\n\n# ------------------------------------ #\n</code></pre></p> <p>Run all tests using the following command from the root of the Clojure project. Kaocha stops if there is a failing task, saving time on running the whole test suite. <pre><code>make test\n</code></pre></p> <p>Use the <code>test-all</code> target to run all unit tests regardless of failures (execept compiler errors)</p> <pre><code>make test-all\n</code></pre> <p>Continually run tests by watching for changes using the <code>:test/watch</code> alias.  If a test fails, Koacha will stop the test run and restart from the failing test when a change is detected.  Use <code>watch-all</code> if all tests should run regardless of failure.</p> <pre><code>make test-watch\n</code></pre> <p> </p> <p>  Practicalli Clojure CLI Config configuration contains aliases to run kaocha test runner, using either the <code>-X</code> or <code>-M</code> execution flag.</p> <p>Run Kaocha using the <code>clojure</code> command in a terminal, using the <code>:test/run</code> which runs all the tests in a project unless a test fails, then kaocha will stop.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Pass <code>:fail-fast? false</code> as an argument to run all tests regardless of test failure.</p> <pre><code>clojure -X:test/run :fail-fast? false\n</code></pre> <p>Continually run tests by watching for changes using the <code>:test/watch</code> alias.  If a test fails, Koacha will stop the test run and restart from the failing test when a change is detected.</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Kaocha recommends adding a <code>bin/kaocha</code> script to each project, although this is optional.  The script calls <code>clojure</code> with a suitable alias and allows for arguments to be passed to the command using <code>\"$@\"</code>.  Command line options will over-ride the same options in the <code>tests.edn</code> file.</p> <p>bin/kaocha<pre><code>#!/usr/bin/env bash\nclojure -M:test/runner \"$@\"\n</code></pre> Use the <code>-M</code> execution option to pass command line flags to the Kaocha test runner.</p> <pre><code>kaocha --fail-fast\n</code></pre>"},{"location":"testing/test-runners/kaocha-test-runner/#configuring-kaocha","title":"Configuring Kaocha","text":"<p>Kaocha can be configure by options in a <code>tests.edn</code> configuration file and options passed via the command line (typically added to the <code>bin/kaocha</code> script).</p> <p>Create a <code>tests.edn</code> file in the root of the project directory and add the default configuration.</p> tests.edn<pre><code>#kaocha/v1 {}\n</code></pre> <p>The <code>tests.edn</code> file and command line options combine to make the complete configuration for the projects in the test.</p> <p><code>make test-config</code> runs <code>clojure -M:test/run --print-config</code> to print out the current kaocha configuration.</p> <p> </p> <p>Use the default configuration as the basis for customising kaocha test runner for the current project.</p> Alternative kaocha configuration with aero <p>juxt/aero reader literals such as #env, #merge, #ref, and #include can be used to provide different options to the kaocha configuration. For example, a file change watcher can be configured to run unless kaocha is running in CI server environment.</p> <p><code>:kaocha/watch #profile {:default true :ci false}</code></p>"},{"location":"testing/test-runners/kaocha-test-runner/#plugins","title":"Plugins","text":"<p>Much of the functionality of Kaocha is provide by plugins</p> <ul> <li>profiling - lists the slowest tests for each test category</li> <li>cucumber - bdd style test</li> <li>junit-xml reports - format used by Continuous Integration servers to display results</li> </ul>"},{"location":"testing/test-runners/kaocha-test-runner/#profiling","title":"Profiling","text":"<p>Show the 3 slowest tests for each category of test, after the test results</p> MakeClojure CLIKaocha Script <p>As a command line option: <pre><code>make test-profile\n</code></pre></p> <p>Pass the profiling plugin as an argument to the Clojure CLI alias using the <code>-M</code> (clojure.main) execution option <pre><code>clojure -M:test/env:test/run --plugin kaocha.plugin/profiling\n</code></pre></p> <p>As a command line option: <pre><code>bin/kaocha --plugin kaocha.plugin/profiling\n</code></pre></p> <p>Or add the profile plugin to the <code>test.edn</code> configuration</p> <pre><code>#kaocha/v1\n{:plugins [:kaocha.plugin/profiling]}\n</code></pre>"},{"location":"testing/test-runners/kaocha-test-runner/#example-testsedn","title":"Example tests.edn","text":"<p> Practicalli Banking-on-Clojure project is a web application backed by a relational database, using kaocha as the test runner.</p> <p><code>:kaocha/tests</code> defines two types of tests.  The hash-map containing <code>:kaocha.testable/id :unit</code> defines the configuration for unit tests using <code>clojure.test</code>.  The hash-map containing <code>:kaocha.testable/id :generative-fdef-checks</code> are generative tests using clojure spec.</p> <p><code>:kaocha/color?</code> and <code>:kaocha/watch</code> use a value dependent on the <code>#profile</code> kaocha is run under.</p> <p>Banking on Clojure project - Kaocha test.edn configuration</p> <pre><code>#kaocha/v1\n{:kaocha/tests\n [{:kaocha.testable/id      :unit\n   :kaocha.testable/type    :kaocha.type/clojure.test\n   :kaocha/ns-patterns      [\"-test$\"],\n   :kaocha/source-paths     [\"src\"],\n   :kaocha/test-paths       [\"test\"],\n   :kaocha.filter/skip-meta [:kaocha/skip]}\n\n  {:kaocha.testable/id            :generative-fdef-checks\n   :kaocha.testable/type          :kaocha.type/spec.test.check\n   :kaocha/source-paths           [\"src\"]\n   :kaocha.spec.test.check/checks [{:kaocha.spec.test.check/syms            :all-fdefs\n                                    :clojure.spec.test.check/instrument?    true\n                                    :clojure.spec.test.check/check-asserts? true\n                                    :clojure.spec.test.check/opts           {:num-tests 10}}]}\n  ]\n\n :kaocha/reporter [kaocha.report/documentation]\n\n :kaocha/color? #profile {:default true\n                          :ci      false}\n\n ;; Run tests of file changes, unless running in CI server\n :kaocha/watch #profile {:default true :ci false}\n\n :kaocha/fail-fast? true\n\n :kaocha.plugin.randomize/randomize? false\n\n :kaocha/plugins\n [:kaocha.plugin/randomize\n  :kaocha.plugin/filter\n  :kaocha.plugin/capture-output\n  :kaocha.plugin.alpha/spec-test-check]\n\n :kaocha.plugin.capture-output/capture-output? true\n }\n</code></pre> <p>The configuration shows how to explicitly configure different sections, although configuration could be streamlined by using more default values.</p>"},{"location":"testing/unit-testing/","title":"Clojure Unit Testing","text":"<p>The function is the unit under test in Clojure.  All public functions that form the API of their respective namespace should have a matching test, i.e. <code>(deftest)</code> definition.</p> <p><code>clojure.test</code> namespace provides functions for defining and running unit tests and is available in the Clojure library for any project to use.</p> <p></p>"},{"location":"testing/unit-testing/#unit-test-principles","title":"Unit Test Principles","text":"<ul> <li>A <code>test</code> namespace for each <code>src</code> namespace under test</li> <li>A <code>deftest</code> function for each function under test, named after the function its testing with <code>-test</code> at the end of the name</li> <li>Multiple assertions (<code>is</code> <code>are</code>) for one function</li> <li><code>is</code> defines an assertion returning true (test pass) or false (test fail), typically a comparison between a known value and the result of a function call</li> <li><code>are</code> to testing similar functionality with different data sets (or use generative testing)</li> <li><code>testing</code> to logically group assertions and provide a meaningful description of that grouping (easier to identify tests when they fail)</li> <li><code>use-fixtures</code> to call fixture functions that setup and tear down any state required for test(s) to run</li> <li>Test API rather than implementation</li> <li>test generic helper or private functions through public functions of each namespace (minimise test churn and time to run all tests)</li> <li><code>^:helper</code> meta-data on <code>deftest</code> for more generic functions, to skip those tests via a test selector</li> <li>Use generative testing to create more maintainable test code with more extensive range of data</li> <li>Use test selectors with a test runner to selectively run tests and optimise speed of test runs</li> <li>Limit mocking of systems to integration tests (although mocking data is good everywhere)</li> </ul> Code should evaluate or have line comments <p>All Clojure code should be valid syntax and able to be evaluated (compiled), even code within a <code>(comment )</code> expression or after a <code>#_</code> reader comment.</p> <p>Code commented with a line comment, <code>;;</code>, will not be read by Clojure and cannot cause compilation errors when evaluated</p>"},{"location":"testing/unit-testing/#running-tests","title":"Running tests","text":"<p>Test runners can run be run in the REPL used for development or run separately via the command line and continuous integration tasks.</p> <p></p>"},{"location":"testing/unit-testing/#run-tests-in-editor-connected-repl","title":"Run tests in Editor connected REPL","text":"<p>Using an editor connected REPL keeps the workflow in one tool and helps maintain focus. Using editor commands to run the tests and navigable error reports provides an effective flow to run and debug issues.</p> <p>Ensure <code>test</code> directory is on the class path when evaluating tests in the REPL, otherwise the <code>(deftest)</code> test definitions may not be found.</p> <p>If functions or their associated tests are changed, they should be evaluated in the REPL before running tests to ensure those changes are loaded into the REPL.</p> <p>If renaming a function or <code>deftest</code>, the original name should be removed from the REPL to avoid phantom tests (older definitions of tests that were evaluated in the REPL and still run, even though those tests are no longer in the source code).</p> <p>Editors may include a command to remove function or test definitions, e.g. CIDER has <code>undef</code> command</p> <p>The original name can also be removed using Clojure <code>(ns-unmap 'namespace 'name)</code>, where namespace is where the name of the function or test is defined and name is the name of the function or test.</p> <pre><code>(ns practicalli.system-monitor)                ; namespace definition\n(defn dashboard [] ,,,)                        ; original function name\n(defn dashboard-page [] ,,,)                   ; new function name\n(undef 'practicalli.system-monitor 'dashboard) ; remove original function name\n</code></pre> <p>Stop and start the REPL process ensures all function and tests are correctly loaded</p>"},{"location":"testing/unit-testing/#command-line-test-runners","title":"Command line test runners","text":"<p>Command line test runners (i.e. koacha, Cognitect Labs) load function and test definitions from the source code files each time, ensuring tests are run and a clean REPL state is created on each run. This clearly defined REPL state is especially valuable for running repeatable integration tests.</p> <p>Automate running the tests using a watch process,  giving instant fast feedback, especially when displaying both the editor and test runner command line.</p> <p>test runner can be configure to run only selective tests (i.e kaocha)</p> <p>Run all tests (including integration tests) via the command line before pushing commits to ensure all changes to the code have been tested.</p> <p>If tests are not running in the REPL or are returning unexpected errors, a command line test runner is a useful way to diagnose if it is the test code or test tools causing the error.</p> <p>The CLI approach is also more robust for longer running tests than running within an editor.</p> <p>Avoid stale tests</p> <p>Running tests via a command line test runner will never experience stale tests, as long as all relevant changes are saved to the source code files.</p>"},{"location":"testing/unit-testing/#run-tests-in-the-repl","title":"Run tests in the REPL","text":"<p><code>clojure.test</code> includes the <code>run-tests</code> function that runs tests (<code>deftest</code> definitions) in given namespaces and <code>run-all-tests</code> which runs all tests in all namespaces.</p> <pre><code>(run-all-tests)  ; run all tests in all namespaces\n\n(run-tests 'practicalli.system-monitor-test) ; run all tests in practicalli.system-monitor-test\n</code></pre> <p><code>run-tests</code> and <code>run-all-tests</code> are a less common approach as the command line and editor driven test runners provide a rich set of features</p>"},{"location":"testing/unit-testing/#project-structure-with-tests","title":"Project structure with tests","text":"<p>For each source code file in <code>src</code> there should be a corresponding file in <code>test</code> directory with the same name and <code>_test</code> postfix.</p> <p>For example, code to test the <code>src/codewars/rock_paper_scissors.clj</code> is saved in the file <code>src/codewars/rock_paper_scissors_test.clj</code> file.</p> <p></p> <p>Example project: CodeWars: Rock Paper Scissors</p>"},{"location":"testing/unit-testing/#source-and-test-namespaces","title":"Source and Test Namespaces","text":"<p>As with file names, the namespaces for each test code file is the same as the source code it is testing, with a <code>-test</code> postfix.</p> <p><code>codewars/rock-paper-scissors</code> source code namespace will have a matching <code>codewars/rock-paper-scissors-test</code> namespace.</p> Create Projects from templates <p>Templates typically include a parallel <code>test</code> and <code>src</code> directory structure.  The <code>clj-new</code> tool has build it templates (app, lib) and will create <code>src</code> and <code>test</code> directories in the projects it creates.</p> <p><code>clojure -T:project/new :template app :name practicalli/rock-paper-scissors-lizard-spock</code></p>"},{"location":"testing/unit-testing/#project-examples-code-challenges-with-unit-tests","title":"Project Examples: Code challenges with unit tests","text":"<ul> <li>TDD Kata: Recent Song-list - simple tests examples</li> <li>Codewars: Rock Paper Scissors (lizard spock) solution - <code>and</code> examples</li> <li>practicalli/numbers-to-words - overly verbose example, ripe for refactor</li> <li>practicalli/codewars-guides - deps.edn projects</li> <li>practicalli/exercism-clojure-guides - Leiningen projects</li> </ul>"},{"location":"testing/unit-testing/#references","title":"References","text":"<ul> <li>Example based unit testing in Clojure - PurelyFunctional.tv</li> </ul>"},{"location":"testing/unit-testing/clojure-test-expectations/","title":"Clojure test Expectations","text":"<p><code>clojure.test.expectations</code> uses the same tooling as <code>clojure.test</code> and only depends on that library.</p>"},{"location":"testing/unit-testing/clojure-test-expectations/#using-a-depsedn-alias","title":"Using a deps.edn alias","text":"<p> Practicalli Clojure CLI Config</p>"},{"location":"testing/unit-testing/clojure-test-expectations/#add-dependency","title":"Add dependency","text":"<p>Edit the deps.edn file for the current project</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/","title":"Configure Unit Testing for deps.edn projects","text":"<p><code>clojure.test</code> namespace is part of the Clojure standard library, so the Clojure library is the only dependency required in the project.</p> <pre><code>{:deps {org.clojure/clojure {:mvn/version \"1.10.3\"}}}\n</code></pre> <p>Unit tests code should reside under the <code>test</code> directory of a project.  The <code>test</code> directory should not be part of the main classpath, otherwise test classes would be included in the project packaging and deployed to production.</p> <p>Use an alias to add the <code>test</code> directory, either from a user level configuration or the Clojure project <code>deps.edn</code> configuration file.</p> <p>{% tabs practicalli=\"practicalli/clojure-deps-edn\", deps=\"Manual deps.edn projects\" %}</p> <p>{% content \"practicalli\" %}</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#adding-test-path","title":"Adding test path","text":"<p>  Practicalli Clojure CLI Config user-level configuration contains several aliases for Clojure and ClojureScript test runners, each alias includes the <code>test</code> directory as an <code>:extra-path</code>.</p> <p><code>:test/env</code> alias is also provided, which simply adds the <code>test</code> directory to the class path. The <code>:test/env</code> alias is useful in concert with other aliases or for editors that have their own built in test runners (e.g. CIDER).</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#using-kaocha-test-runner","title":"Using kaocha test runner","text":"<p>lambdaisland/kaocha is a fast and comprehensive test runner for Clojure and ClojureScript.</p> <p><code>:test/run</code> alias runs all tests from the source code files, called with the <code>clojure</code> command in the root of the Clojure project.  The alias includes <code>test</code> as an extra path and calls the Kaocha test runner.</p> <pre><code>clojure -X:test/run\n</code></pre> <p>Kaocha can also watch for changes saved to file and re-run the tests.</p> <pre><code>clojure -X:test/watch\n</code></pre> <p>Both kaocha aliases are configured to stop if a test fails.  When re-running kaocha, only failed tests and tests that have changed are run (including tests where the code they are testing has changed).</p>"},{"location":"testing/unit-testing/configure-projects-for-tests/#alias-to-include-the-test-directory","title":"Alias to include the test directory","text":"<p>Add the following aliases to the Clojure CLI tools user wide configuration, (e.g. <code>~/.clojure/deps.edn</code>), or to the project <code>deps.edn</code> file.</p> <p>To use a test runners with a <code>deps.edn</code> projects, the <code>test</code> directory should be on the classpath.</p> <p>practicalli/clojure-deps-edn defines an environment alias to include the test path.</p> <pre><code>:aliases\n{\n  :test/env\n  {:extra-paths [\"test\"]}\n}\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#cognitect-labs-clojure-test-runner","title":"Cognitect labs Clojure test runner","text":"<p><code>:test/cognitect</code> is a simple to use test runner for Clojure projects.</p> <pre><code>clojure -X:test/cognitect\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#kaocha-unit-test-and-clojure-spec-runner","title":"Kaocha unit test and clojure spec runner","text":"<p><code>:test/kaocha</code> alias unit test runner that also supports Clojure Spec functional tests.  the kaocha test runner on the current project.  Add a <code>test.edn</code> file to configure which tests are run by kaocha.</p> <pre><code>clojure -X:test/kaocha\n</code></pre>"},{"location":"testing/unit-testing/configure-projects-for-tests/#references","title":"References","text":"<ul> <li>Practicalli Spacemacs - Unit testing with Cider and Kaocha in Emacs</li> <li>lambdaisland/kaocha is a test runner that supports Clojure CLI, Leiningen and Boot project configuration.</li> <li>Leiningen project configuration for unit testing</li> </ul>"},{"location":"testing/unit-testing/fixtures/","title":"Test Fixtures","text":"<p>Unit tests may require the system to be in a particular state before running a test.  The state may need to be reset after running a test such as a database</p> <p>Fixtures allow you to run code before and after tests, to set up the context in which tests should be run.  Consider when fixtures should be run, especially fixtures that take a noticeable time to setup or tear down.</p> <p>Slow running unit tests lead to unit tests not being run so often and therefore limit their value.</p> <p>Organise tests with test selectors</p> <p>Tests with fixtures may be slower to run so separate them by using a test selector, a piece of meta data attached to a <code>deftest</code> definition. For example, add the <code>^:persistence</code> meta data to test that require database fixtures  (deftest ^:database db-bulk-upload).  The test runner can be instructed to skip or focus on tests with specific meta data.</p>"},{"location":"testing/unit-testing/fixtures/#defining-a-fixture","title":"Defining a fixture","text":"<p>Require the <code>use-fixtures</code> function in the require expression for <code>clojure.test</code></p> <pre><code>(ns domain.application-test\n  (:require [clojure.test :refer [deftest is testing use-fixtures]]))\n</code></pre> <p>A fixture is a standard Clojure function which takes a function as an argument.  The function passed as an argument is either an individual test or all tests in the namespace, depending on how the fixture is used.</p> <pre><code>(defn my-fixture [test-run]\n   ;; Setup: define bindings, create state, etc.\n\n  (test-run) ;; Run the relevant tests for the fixture (see `use-fixtures`)\n\n   ;; Tear-down: reset state to a known value\n )\n</code></pre>"},{"location":"testing/unit-testing/fixtures/#when-to-run-fixtures","title":"When to run fixtures","text":"<p>The <code>use-fixtures</code> function defines when a fixture should be called when running the unit tests in each namespace.  All Clojure unit test runners should support the <code>use-fixtures</code> definitions when running the tests.</p> When Description <code>(use-fixtures :once fixture1 fixture2)</code> Run the fixtures once for the namespace. <code>(use-fixtures :each fixture1 fixture2)</code> Run the fixtures for each <code>deftest</code> in the namespace <p>Once</p> <p>The setup in the fixture is run, followed by all the <code>deftest</code> functions in the namespace, then the fixture tear-down is run.</p> <p>Running a fixture once per namespace is useful for establishing a database connection or creating a particular state of data for all the unit tests to use.</p> <p>Each</p> <p>The fixture setup is run before each <code>deftest</code> function in the namespace. The fixture tear-down is run after each <code>deftest</code> function.</p>"},{"location":"testing/unit-testing/fixtures/#anonymous-function-fixture","title":"Anonymous function fixture","text":"<p>The <code>use-fixtures</code> function can also include anonymous function as well as a namespace scoped functions (<code>deftest</code>).</p> <pre><code>(use-fixtures :each (fn [f] #_setup... (f) #_teardown))\n</code></pre> <p><code>defn</code> functions are usually recommended unless the fixture code is relatively terse.</p> <p>Development database</p> <p>Define a fixture to reset the database before running a test and clear the database after each test.</p> <p>The <code>create-database</code> and <code>delete-database</code> are helper functions that are part of the namespace under test.</p> <pre><code>(defn database-reset-fixture\n  \"Setup: drop all tables, creates new tables\n   Teardown: drop all tables\n  SQL schema code has if clauses to avoid errors running SQL code.\n  Arguments:\n  test-function - a function to run a specific test\"\n  [test-function]\n  (SUT/create-database)\n  (test-function)\n  (SUT/delete-database))\n</code></pre> <p>The fixture should be used for each unit test (<code>deftest</code>) that is defined in the namespace the <code>database-reset-fixture</code> is defined in.</p> <pre><code>(use-fixtures :each database-reset-fixture)\n</code></pre>"},{"location":"testing/unit-testing/fixtures/#references","title":"References","text":"<ul> <li><code>use-fixtures</code> - Clojuredocs.org</li> <li>Kaocha - focusing and skipping</li> <li>Clojure Test Fixtures - astrocaribe</li> </ul>"},{"location":"testing/unit-testing/test-selectors/","title":"Test Selectors","text":"<p>As a project grows in scope its important that tests continue to run quickly.  Test runs which take a noticeable time to complete diminish the motivation to run tests frequently.</p> <p>Divide tests into categories to run selective tests, continuing to provide fast feedback.  Longer running tests can be run less often without loosing quality in the feedback from tests.</p> <p>Test runners use test selectors to run a specific categories, or exclude test selectors so all tests except that category runs.</p> <p>kaocha focus and skipping</p> <p>kaocha can group tests into categories in the <code>tests.edn</code> configuration, providing a way to focus or exclude different types of tests (e.g. <code>:unit</code> and <code>:spec</code>)</p>"},{"location":"testing/unit-testing/test-selectors/#test-category-metadata","title":"Test category metadata","text":"<p>Add metadata to <code>deftest</code> functions to provide categories of tests, e.g. <code>integration</code>, <code>persistence</code>, etc.</p> <pre><code>(deftest ^:integration register-customer\n  (is ,,,))\n</code></pre> <p>Example from Banking on Clojure</p> <pre><code>(deftest ^:persistence new-customer-test\n  (testing \"New customer generative testing\")\n  (is (spec/valid?\n        :customer/id\n        (:customer/id (SUT/new-customer\n                        (spec-gen/generate (spec/gen :customer/unregistered)))))))\n</code></pre>"},{"location":"testing/unit-testing/test-selectors/#test-selectors_1","title":"Test Selectors","text":"<p>Start a test selective category of tests running by specifying test selectors to include or exclude.</p> KaochaSpacemacsCiderCognitect <p>kaocha supports meta data on <code>deftest</code> expressions and has its own metadata tag for skipping tests, <code>^:koacha/skip</code></p> <p>Examples of tests with and without test selectors</p> <pre><code>(deftest simple-test\n  (is (= 1 1)))\n\n(deftest ^:integration system-update-test\n  (is (spec/valid? :system/update (long-running-function))))\n\n(deftest ^:kaocha/skip under-development-test\n  (is (= 3 21/7)))\n</code></pre> <p>Tests with test selector metadata can be skipped using a <code>tests.edn</code> configuration</p> <pre><code>#kaocha/v1\n{:tests [{:kaocha.filter/skip-meta [:integration]}]}\n</code></pre> <p>Running kaocha will only run the <code>simple-test</code>, skipping the other two tests.</p> <p>Specifying <code>--skip-meta</code> on the command line gives the same results</p> <pre><code>bin/kaocha --skip-meta :metadata-name\n</code></pre> <p>Running tests with the universal argument will prompt for test selector filters and only Run those tests that match the selector inclusions/exclusions.</p> <p><code>SPC u , t a</code> runs all tests, prompting for tests selector names to include (space separated)</p> <p></p> <p>Then prompting for the test selectors to exclude.  A warning displays if CIDER does not find the test selector name.</p> <p></p> <p>Invoke the CIDER test runner commands with the universal argument and CIDER will prompt for test selector filters, running only those tests that match the selector inclusions/exclusions.</p> <p><code>C-c C-t p</code> runs all the tests in a project.</p> <p><code>C-u C-c C-t p</code> prompts for test selectors and runs the matching tests in a project.</p> <p><code>C-c C-t l</code> runs all tests currently evaluated in the REPL.</p> <p><code>C-u C-c C-t l</code> prompts for test selectors and runs the matching tests currently evaluated in the REPL.</p> <p>CIDER first prompts for the test selectors to include:</p> <p></p> <p>Then prompts for the test selectors to exclude.  A warning displays if CIDER does not find the test selector name.</p> <p></p> <p>The Cognitect Labs test runner uses command line options to specify test selectors, <code>--include</code> and <code>--exclude</code>.</p> <p>  Practicalli Clojure CLI Config configuration provides the <code>:test/congnitect</code> alias.</p> <p><code>clojure -M:test/cognitect --include :database</code> only runs tests with the <code>^:database</code> test selector</p> <p><code>clojure -M:test/cognitect --exclude :integration</code> runs all tests except those with the <code>^:integration</code> test selector</p>"},{"location":"testing/unit-testing/test-selectors/#references","title":"References","text":"<ul> <li>Kaocha - Focus and skipping tests with test selectors</li> <li>Convoluted Magic of Leiningen Test Selectors</li> <li>How to use Leiningen test selectors to filter by test name</li> <li>Stack overflow - Lein test with Selectors - how to specify a test for multiple conditions</li> </ul>"},{"location":"testing/unit-testing/writing-unit-tests/","title":"Writing Unit Tests with clojure.test","text":"<p>Unit tests are centered on assertions, testing if something returns a true or false value.</p> <p><code>is</code> function is the simplest assertion and the most common.  It checks to see if an expression given is true and if so then the assertion passes.  If the value is false then that assertion fails.</p> <p><code>as</code> provides a way to run the same assertion with different values, testing the same function with a collection of arguments.  This provides a clean way to test a function without lots of repetition.</p> <p><code>testing</code> is a macro to group multiple assertions together, providing a string in which to describe the context the assertions are testing.  The well worded context string is invaluable for narrowing down on which assertions are failing.</p> <p><code>deftest</code> is a collection of assertions, with or without <code>testing</code> expressions.  The name of the deftest should be the name of the function it is testing with <code>-test</code> as a postfix.  For example, the function <code>practicalli.playground/calculator</code> would have a <code>deftest</code> called <code>practicalli.playground-test/calculator-test</code></p>"},{"location":"testing/unit-testing/writing-unit-tests/#requiring-namespaces","title":"Requiring Namespaces","text":"<p>A test namespace has a singular purpose to test a matching src namespace.</p> <p>The idiomatic approach is to <code>:refer</code> specific functions from <code>clojure.test</code> as those functions are used.</p> <p>The namespace to be tested is referred using a meaningful alias. The alias highlight the exact functions being tested in the body of the code.  This provides a visual way to separate functions under test with other test functions, especially if there are helper functions or vars used for test data.</p> REPLproject <p><pre><code>(require '[clojure.test :refer [are deftest is testing]])\n</code></pre> The namespace under test should be referred using the alias so they are readily identified within the test code. <pre><code>(require '[practicalli.gameboard.spec :as gameboard-spec])\n</code></pre></p> <p>Add <code>clojure.test</code> to the namespace definition along with the namespace under test. <pre><code>(ns practicalli.app-namespace-test\n  (:require '[clojure.test :refer [are deftest is testing]]\n             [practicalli.gameboard.spec :as gameboard-spec]))\n</code></pre></p>"},{"location":"testing/unit-testing/writing-unit-tests/#simple-example","title":"Simple Example","text":"<pre><code>(deftest public-function-in-namespace-test\n  (testing \"A description of the test\"\n    (is (= 1 (public-function arg)))\n    (is (predicate-function? arg))))\n</code></pre>"},{"location":"testing/unit-testing/writing-unit-tests/#assertion-data-set","title":"Assertion data set","text":"<p>The <code>are</code> macro can also be used to define assertions, especially when there would otherwise be multiple assertions that only differ by their test data.</p> <p>An <code>are</code> assertion defines the arguments to the test, the logic of the test and a series of test data.</p> <pre><code>(are [x y] (= x y)\n              2 (+ 1 1)\n              4 (* 2 2))\n</code></pre> <p>This is equivalent to writing</p> <pre><code>         (do (is (= 2 (+ 1 1)))\n             (is (= 4 (* 2 2))))\n</code></pre> <p>Refactor test assertion to use data set</p> <p>Assertions in the test take the same shape of values, so are candidates to refactor to the <code>are</code> macro. <pre><code>(deftest encoder-test\n  (testing \"Tens to number words\"\n    (is (= '(\"zero\" \"ten\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\1 \\0))))\n    (is (= '(\"zero\" \"eleven\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\1 \\1))))\n    (is (= '(\"zero\" \"twenty\" \"zero\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\2 \\0))))\n    (is (= '(\"zero\" \"twenty\"\"one\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\2 \\1))))\n    (is (= '(\"zero\" \"forty\" \"two\")\n           (character-sequence-&gt;word-sequence dictionary/digit-&gt;word '(\\0 \\4 \\2))))))\n</code></pre> Refactor the assertions using are simplifies the code, making it simpler to change further and extend with more data. <pre><code>(deftest encoder-test\n  (testing \"Tens to number words\"\n    (are [words numbers]\n      (= words (character-sequence-&gt;word-sequence dictionary/digit-&gt;word numbers))\n        '(\"zero\" \"ten\")           '(\\0 \\1 \\0)\n        '(\"zero\" \"eleven\")        '(\\0 \\1 \\1)\n        '(\"zero\" \"twenty\" \"zero\") '(\\0 \\2 \\0)\n        '(\"zero\" \"twenty\"\"one\")   '(\\0 \\2 \\1)\n        '(\"zero\" \"forty\" \"two\")   '(\\0 \\4 \\2)))\n</code></pre></p> <p>Generative Testing provides a wide range of values</p> <p>Generating test data from Clojure Specs provides an extensive set of values that provide an effective way to test functions.</p>"},{"location":"testing/unit-testing/writing-unit-tests/#reference","title":"Reference","text":"<p>clojure.test API</p>"},{"location":"testing/unit-testing/writing-unit-tests/#code-challenges-with-tests","title":"Code challenges with tests","text":"<p>TDD Kata: Recent Song-list TDD Kata: Numbers in words Codewars: Rock Paper Scissors (lizard spock) solution practicalli/codewars-guides practicalli/exercism-clojure-guides</p>"},{"location":"thinking-functionally/","title":"Thinking Functionally","text":"<p>In this section I cover some simple examples of Clojure code to help you think about the concepts involved in functional programming.</p> <p>An overview of thinking functionally is also covered in the presentation entitled Getting into Functional Programming with Clojure on slideshare and its accompanying youtube video</p> Get into Functional Programming with Clojure  from John Stevenson <p></p> <p>Get a free Clojurians slack community account</p>"},{"location":"thinking-functionally/arity/","title":"Arity","text":"<p>Fixme work in progress</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/","title":"Example: Hitchhikers Guide","text":"<p>This is an example of using the threading macros and  a REPL to give fast feedback as you are developing code.</p> <p>Suggest you use the assumed perfectly legal copy of the Hitch-hickers book text using the <code>slurp</code> function</p> <p>Approximate algorithm</p> <ul> <li>Use a regular expression to create a collection of individual words - eg. #\"[a-zA-Z0-9|']+\"</li> <li>Convert all the words to lower case so they match with common words source - <code>clojure.string/lower-case</code></li> <li><code>Remove</code> the common English words used in the book, leaving more context specific words</li> <li>Calculate the <code>frequencies</code> of the remaining words, returning a map of word &amp; word count pairs</li> <li><code>Sort-by</code> word count values in the map</li> <li><code>Reverse</code> the collection so the most commonly used word is the first element in the map</li> </ul> <pre><code>(def book (slurp \"http://clearwhitelight.org/hitch/hhgttg.txt\"))\n\n(def common-english-words\n  (-&gt; (slurp \"https://www.textfixer.com/tutorials/common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n\n;; using a function to pull in any book\n(defn get-book [book-url]\n  (slurp book-url))\n\n\n(defn -main [book-url]\n  (-&gt;&gt; (get-book book-url)\n       (re-seq #\"[a-zA-Z0-9|']+\")\n       (map #(clojure.string/lower-case %))\n       (remove common-english-words)\n       frequencies\n       (sort-by val)\n       reverse))\n\n;; Call the program\n\n(-main \"http://clearwhitelight.org/hitch/hhgttg.txt\")\n</code></pre>"},{"location":"thinking-functionally/example-hitchhikers-guide/#note","title":"NOTE","text":"<p>Write functions that will give a list of the most used words used in a book, excluding the common English words like \"the, and, it, I\".  Join those functions with a threading macro.</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/#deconstructing-the-code-in-the-repl","title":"Deconstructing the code in the repl","text":"<p>To understand what each of the functions do in the <code>-main</code> function then you can simply comment out one or more expressions using in front of the expression #_</p> <pre><code>(defn -main [book-url]\n  (-&gt;&gt; (get-book book-url)\n       #_(re-seq #\"[a-zA-Z0-9|']+\")\n       #_(map #(clojure.string/lower-case %))\n       #_(remove common-english-words)\n       #_frequencies\n       #_(sort-by val)\n       #_reverse))\n</code></pre> <p>Now the <code>-main</code> function will only return the result of the <code>(get-book book-url)</code> function.  To see what each of the other lines do, simply remove the #_ character from the front of an expression and re-evaluate the <code>-main</code> function in the repl</p> <p>Hint In Spacemacs / Emacs, the keybinding C-c C-p show the output in a separate buffer.  Very useful when the function returns a large results set.</p>"},{"location":"thinking-functionally/example-hitchhikers-guide/#off-line-sources-of-hitch-hickers-book-and-common-english-words","title":"Off-line sources of Hitch-hickers book and common English words","text":"<pre><code>(def book (slurp \"./hhgttg.txt\"))\n\n(def common-english-words\n  (-&gt; (slurp \"common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre> <p>Original concept from Misophistful: Understanding thread macros in clojure</p> <p>Hint The <code>slurp</code> function holds the contents of the whole file in memory, so it may not be appropriate for very large files.  If you are dealing with a large file, consider wrapping slurp in a lazy evaluation or use Java IO (eg. <code>java.io.BufferedReader</code>, <code>java.io.FileReader.</code>).  See the Clojure I/O cookbook and The Ins &amp; Outs of Clojure for examples.</p>"},{"location":"thinking-functionally/first-class-functions/","title":"First Class functions","text":"<p>Idempotent - given the same input you get the same output</p> <pre><code>(+ 1 2 3 4 5 6 7 8 9 10)\n</code></pre> <p>The <code>range</code> function generates a sequence of numbers and when given arguments it does so from a specific range.  The second number is exclusive, so for 1 to 10 the second argument should be 11.</p> <pre><code>(range 1 11)\n</code></pre> <p>Unfortunately we cant just add the result of a range, because it returns a lazy sequence  So <code>(range)</code> by itself will create an error</p> <pre><code>(+ 1 (range 1 11))\n</code></pre> <p>Using a function called <code>reduce</code> we can calculate a single total value from all the numbers in the collection.</p> <p>The reduce function take 2 arguments, the first is the function to apply to a data structure, the second is the data structure.</p> <pre><code>(reduce + (range 1 11))\n\n(reduce + (1 2 3 4 5 6 7 8 9 10))\n</code></pre>"},{"location":"thinking-functionally/first-class-functions/#note","title":"Note::","text":"<p>Write an expression to add up the numbers from 1 to 10 and return the overall total.</p>"},{"location":"thinking-functionally/first-class-functions/#note_1","title":"Note::","text":"<p>Create an expression to do the same calculation, but without having to write all the numbers.  Hint: consider the functions called range and reduce.</p>"},{"location":"thinking-functionally/function-composition/","title":"Function Composition","text":"<p>We have discussed how functional programs are essentially a number of functions that work together, this is called composition (functional composition).</p> <pre><code>(let [calculated-value (* 10 (reduce +  (map inc (range 5))))]\n  calculated-value)\n</code></pre> <p>This expression is common in the Lisp &amp; Clojure languages.  Occasionally the created expressions can becomes challenging to read.  To overcome this parsing complexity, developers often break down a more complex expression into its parts, extracting code into its own function.</p> <p>Note Brake down the above example into each expression that gives a value</p> <pre><code>(range 5)\n\n(map inc (range 5))\n\n(reduce +  (map inc (range 5)))\n\n(* 10 (reduce +  (map inc (range 5))))\n\n\n;; Additional examples\n\n;; Use a let expression for code that is used more than once in a function\n\n(let [calculated-value (* 10 (reduce +  (map inc (range 5))))]\n  calculated-value)\n\n;; Use defn to define a function for code that multiple functions will call\n;; and generalise the function with arguments\n\n(defn common-data-calculation\n  [certainty-factor scope]\n  (* certainty-factor (reduce +  (map inc (range scope)))))\n</code></pre>"},{"location":"thinking-functionally/functors/","title":"Functors","text":"<p>Fixme work in progress</p> <p>Put simply, a function that takes a value and a function as its arguments, eg <code>map</code>.  The argument pass as a value is most commonly a collection type (vector, map, string, list).</p> <p>From Wikipedia</p> <p>In mathematics, a functor is a type of mapping between categories which is applied in category theory. Functors can be thought of as homomorphisms between categories. In the category of small categories, functors can be thought of more generally as morphisms.</p> <p>A functor applies the given function to each element in the the collection by unpacking and each element from the collection and passing it to the function as an argument.  The result from each application of the function from the element of the collection is put into a new collection.  This new collection is returned once all elements of the original collection have been processed.</p> <p>The function, eg. + is applied in turn to each value and returns a structured value as a result, eg. a list or vector</p> <pre><code>(map inc [1 2 3 4 5])\n\n(inc 1 )\n</code></pre>"},{"location":"thinking-functionally/higher-order-functions/","title":"Higher Order functions","text":"<p>Functions can be used as an arguments to other functions as we have seen in function composition.  This is possible because a function always evaluates to a value.  This is the basis of function composition.</p> <p>Higher Order functions can also return a function definition, as when that function definition is evaluated it to will return a value.</p> <p>You could have a function that returns a function definition which in turn returns a function definition, but at some point this will get very confusing for the developers (yes, that means you).</p> <pre><code>(filter\n even?\n (range 1 10))\n</code></pre> <pre><code>(defn twice [f]\n  ,,,)\n</code></pre> <pre><code>;; Our higher order function\n\n(defn twice [function x]\n  (function (function x)))\n\n(twice\n  (fn [arg]\n    (* 3.14 arg))\n  21)\n;; =&gt; 207.0516\n\n;; using the short syntax for a function definition\n\n(twice #(+ 3.14 %) 21)\n;; =&gt; 207.0516\n</code></pre> <pre><code>(defn calculation [f]\n  ,,,)\n</code></pre> <pre><code>(defn calculation [f]\n  (fn [&amp; args]\n    (reduce f args)))\n\n((calculation +) 1 1 2 3 5 8 13)\n\n;; The result of `(calculation +)` is also in a list,\n;; so it will be called as a function, with the arguments 1 1 2 3 5 8 13\n</code></pre>"},{"location":"thinking-functionally/higher-order-functions/#notereturn-the-even-numbers-from-1-to-10","title":"Note::Return the even numbers from 1 to 10","text":"<p>Generate a range of numbers from 1 to 10</p> <p>Use a function that checks if a number is even and filter the range of numbers to return only the numbers that match</p>"},{"location":"thinking-functionally/higher-order-functions/#notecreate-a-named-function-as-a-higher-order-function-called-twice","title":"Note::Create a named function as a higher order function called <code>twice</code>","text":"<p>The function twice which takes a function and value as arguments.</p> <p>The twice function should call the function passed as an argument on the value passed as an argument.</p> <p>The result should be then used as an argument to calling the function passed as an argument again.</p> <p>Call the twice function with an inline function which takes a number as an argument and adds it to Pi, <code>3.14</code>.</p>"},{"location":"thinking-functionally/higher-order-functions/#notedefine-a-function-that-returns-a-function","title":"Note::Define a function that returns a function","text":"<p>The function should take a clojure.core function for a mathematical calculation, i.e. <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code></p> <p>The returning function should take one or more arguments <code>[&amp; args]</code> and use the function originally passed as an argument to <code>reduce</code> the data to a single value.</p>"},{"location":"thinking-functionally/higher-order-functions/#references","title":"References","text":"<ul> <li>Writing Elegant Clojure code using Higher Order functions</li> </ul>"},{"location":"thinking-functionally/homoiconicity/","title":"Homoiconicity","text":"<p>Clojure is a homoiconic language, which is a term describing the fact that Clojure programs are represented by Clojure data structures.</p> <p>In Clojure you write your business logic as functions.  A function is defined using a list structure.  A function is called using a list structure, as the first element of a list is evaluated as a function call.</p> <p>Hint Everything in Clojure is a List (or vector, map, set).</p> <p>This is a very important difference between Clojure (and Common Lisp) and most other programming languages - Clojure is defined in terms of the evaluation of data structures and not in terms of the syntax of character streams/files.</p> <p>It is quite easy for Clojure programs to manipulate, transform and produce other Clojure programs.  This is essentially what macros do in Clojure, they re-write Clojure for you.</p> <p>Hint If you were going to create Skynet, it would be so much easier to do in Clojure</p> <p></p>"},{"location":"thinking-functionally/homoiconicity/#an-example","title":"An example","text":"<p>Consider the following expression:</p> <pre><code>(let [x 1] \n    (inc x))\n</code></pre> <p>Evaluating the above code in the REPL returns <code>2</code> because the repl compiles and executes any code entered into it. But <code>[x 1]</code> is also a literal vector data structure when it appears in a different context.</p> <p>All Clojure code can be interpreted as data in this way. In fact, Clojure is a superset of EDN \u2013 Extensible Data Notation, a data transfer format similar to JSON. EDN supports numbers, strings, lists (1 2 3), vectors [1 2 3], maps {\"key\" \"value\"}.</p> <p>If this sounds and looks a lot like Clojure syntax, it\u2019s because it is. The relationship between Clojure and EDN is similar to that of Javascript and JSON, but much more powerful.</p> <p>In Clojure, unlike JavaScript, all code is written in this data format. We can look at our let statement not as Clojure code, but an EDN data structure. Let\u2019s take a closer look:</p> <pre><code>(let [x 1] \n    (inc x))\n</code></pre> <p>In this data structure, there are four different types of data.</p> <ul> <li>1 is a literal integer.</li> <li>let, x, and inc are symbols. A symbol is an object representing a name \u2013 think a string, but as an atomic object and not a sequence of characters.</li> <li>[x 1] is a vector containing two elements: symbol, x, and an integer, 1. Square brackets always signify vectors when talking about EDN data structures.</li> <li>(inc x) is a list (a linked list data structure) containing two symbols, inc and x.</li> </ul> <p>When thinking about a piece of Clojure code as a data structure, we say we are talking about the form. Clojure programmers don\u2019t normally talk about EDN, there are just two ways to think about any bit of Clojure: 1) as code that will execute or 2) as a form, a data structure composed of numbers, symbols, keywords, strings, vectors, lists, maps, etc.</p> <p>Symbols are particularly important. They are first class names. In Clojure, we distinguish between a variable and the name of that variable. When our code is executing, x refers to the variable established by our let binding. But when we deal with that code as a form, x is just a piece of data, it\u2019s a name, which in Clojure is called a symbol.</p> <p>This is why Clojure is homoiconic. Code forms are data structures and data structures can be thought of as forms and executed as code. This transformation is quite literal, and two core operations, quote and eval are key ingredients to this potion.</p>"},{"location":"thinking-functionally/homoiconicity/#references","title":"References","text":"<ul> <li>The Reader - Clojure. org</li> <li>Homoiconicity - Wikipedia</li> <li>Is Clojure Homoiconic - muhuk.com</li> <li>Understanding Homoiconicity in Clojure - Drew Colthorp</li> </ul>"},{"location":"thinking-functionally/immutability/","title":"Immutability","text":"<p>There is a strong emphasis on immutability in Clojure.  Rather than create variables that change, Clojure uses values that do not change.</p> <p>Values in Clojure include numbers, characters, strings.</p> <p>When functions act on values, a new value is created and returned, rather than modifying the existing value.</p> <p>TODO include a diagram to visualise this...</p>"},{"location":"thinking-functionally/immutability/#immutabile-data-structures","title":"Immutabile data structures","text":"<p>List, Map, Vector and Set are all immutable data structures in Clojure.</p> <p>So when you use these data structures with a function, a new data structure is returned.</p> <p>Hint When a new data structure is created from an existing data structure, then under the covers the two data structures actually share memory use for any elements that are common.  This keeps copies very cheap to create in terms of memory used.</p> <p>See the section on data structures for more details.</p>"},{"location":"thinking-functionally/immutable-collections/","title":"Immutable collections","text":"<p>As we have discussed, immutable data structures cannot be changed.  So when you run a function over a collection a copy of that collection is returned.  Lets see this by running some code in the REPL.</p> <p>Note Define a data structure called <code>numbers</code> using a vector.  Then write a function that uses the <code>map</code> and <code>inc</code> function to increment all the numbers in a vector.</p> <p>Then check the current value of the <code>numbers</code> data structure by evaluating its name.</p> <pre><code>;; define the data structure \n(defn numbers [1 2 3 4 5])\n\n;; increment the numbers\n(map inc numbers)\n\n;; see the current value of numbers\nnumbers\n</code></pre> <p>Note Use the <code>conj</code> function to first add the number <code>5</code> to the <code>numbers</code> vector from the previous exercise and check the value of <code>numbers</code>.  Then add the number <code>6</code> to the <code>numbers</code> vector and check the value of <code>numbers</code>.</p> <p>Finally, use the <code>conj</code> function to add both <code>5</code> and <code>6</code> to the <code>numbers</code> vector and check the value of <code>numbers</code></p> <pre><code>(def numbers [1 2 3 4])\n\n;; add 5 to the numbers vector\n(conj numbers 5)\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n\n;; add 6 to the numbers vector\n(conj numbers 6)\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n\n;; add 5 and 6 to the numbers vector\n(conj numbers 5 6)\n\n;; Alternatively, you can use the threading macro to chain two conj function calls\n(-&gt; numbers\n    (conj 5)\n    (conj 6))\n\n;; check the value of numbers\nnumbers\n;; =&gt; [1 2 3 4]\n</code></pre> <p>So even though we have applied several functions on the <code>numbers</code> data structure it still has the same value.</p>"},{"location":"thinking-functionally/immutable-local-bindings/","title":"Immutable Local Bindings","text":"<p>Names can be bound to values &amp; and data structures with either the <code>def</code> or <code>let</code> function.  The <code>def</code> binding is global to the namespace, however the <code>let</code> function is local to its use.</p> <p>Hint The <code>let</code> function is typically used to define names within a function definition, or in snippets of code created during repl driven development.</p> <pre><code>(let [five 5]\n  (str \"Within the let expression the value is \" five))\n;; =&gt; Within the let expression the value is 5\n\n;; evaluating the name five outside the let expression returns an error\nfive\n;; =&gt; Unable to resolve symbol: five in this context\n</code></pre> <p>Note Create a local binding called number that represents the value 5 using the <code>let</code> function. Increment the number, then print out the value of number.</p> <pre><code>(let [number 5]\n   (inc number)\n   (str \"The number is still \" number))\n</code></pre> <p>So the value that any local binding points to is immutable too.</p>"},{"location":"thinking-functionally/immutable-values/","title":"Immutable values","text":"<p>Fixme work in progress</p> <p>Values in Clojure include numbers, characters and strings.  When you use functions on these values they do not change, instead a new value is returned.</p> <p>Lets look at a simple example with a number:</p> <pre><code>(def two-little-ducks 22)\n\n(inc two-little-ducks)\n;; =&gt; 23\n\ntwo-little-ducks\n;; =&gt; 22\n</code></pre> <p>Another example with a string:</p> <pre><code>(def message \"Strings are immutable\")\n\n(str message \",\" \" \" \"you cant change them\")\n;; =&gt; \"Strings are immutable, you cant change them\"\n\nmessage\n;; =&gt; \"Strings are immutable\"\n</code></pre> <p>Fixme Add an exercise</p>"},{"location":"thinking-functionally/impure-functions/","title":"Impure functions","text":"<p>We have seen some simple examples of pure functions, so lets see impure functions as a comparison.</p> <pre><code>(def global-value '(5 4 3 2 1))\n\n(defn impure-increment-numbers [number-collection]\n  (map inc global-value))\n\n(impure-increment-numbers '(1 2 3 4 5))\n</code></pre> <p>The above function is using a global value rather than the argument passed makes this function deterministic</p>"},{"location":"thinking-functionally/impure-functions/#side-effect-printing-to-the-console-log","title":"Side Effect: Printing to the console log","text":"<p>Although the following example is probably quite harmless, it is a simple example of a function effecting the state of something outside.  These side effects should be avoided where possible to keep your code simpler to reason about.</p> <pre><code>(defn print-to-console [value-to-print]\n  (println \"The value is:\" value-to-print))\n\n(print-to-console \"a side effect\")\n</code></pre>"},{"location":"thinking-functionally/impure-functions/#side-causes-calling-libraries","title":"Side Causes: Calling libraries","text":"<p>To demonstrate a side causes form of impure functions, lets create a task-comple function that marks a current task complete using the current timestamp.</p> <pre><code>(defn task-complete [task-name]\n  (str \"Setting task \" task-name \" completed on \" (js/Date)))\n\n(task-complete \"hack clojure\")\n</code></pre> <pre><code>(:import java.util.Date)\n\n(defn task-complete [task-name]\n  (str \"Setting task \" task-name \" completed on \" (java.util.Date.)))\n\n(task-complete \"hack clojure\")\n</code></pre> <p>In this example we have called to the outside world to generate a value for us.  The above example is fairly simple, however by calling the outside world rather than passing in a date it makes the functions purpose far less clear.</p>"},{"location":"thinking-functionally/impure-functions/#hint-the-function-javautildate-is-actually-a-call-to-instantiate-a-javautildate-object-the-full-stop-character-at-the-end-of-the-name-makes-it-a-function-call-and-is-the-short-form-of-new-javautildate","title":"Hint:: The function <code>(java.util.Date.)</code> is actually a call to instantiate a java.util.Date object.  The full-stop character at the end of the name makes it a function call and is the short form of <code>(new java.util.Date)</code>","text":""},{"location":"thinking-functionally/impure-functions/#re-write-as-a-pure-function","title":"Re-write as a pure function","text":"<p>Change the task-complete function definition and function call to take both the task-name and completed-date as arguments.</p> <pre><code>(defn task-complete [task-name completed-date]\n  (str \"Setting task \" task-name \" completed on \" completed-date))\n\n(task-complete \"hack clojure\" (js/Date))\n</code></pre> <p>Required values should be generated outside a function where possible.  In this case in the <code>(js/Date)</code> function is first evaluated and replaced by its value, then that date value is passed to the function as an argument, keeping the function pure.</p> <p>The pure version of the function in Clojure, using the java.util.Date function.</p> <pre><code>(:import java.util.Date)\n\n(defn task-complete [task-name completed-date]\n  (str \"Setting task \" task-name \" completed on \" completed-date))\n\n(task-complete \"hack clojure\" (java.util.Date.))\n</code></pre>"},{"location":"thinking-functionally/iterate-over-values/","title":"iterate Over Values","text":"<p>This</p> <ul> <li>loop recur</li> <li>reducing functions</li> <li>map apply reduce</li> <li>partition group-by sort-by</li> </ul>"},{"location":"thinking-functionally/iterate-over-values/#hintwork-in-progress","title":"Hint::Work in progress","text":""},{"location":"thinking-functionally/iterate-over-values/#loop-recur","title":"loop recur","text":"<p>loop recur is a very detailed way of defining a way to iterate over values. map, reduce and apply are commonly used abstractions for iterating over values. They simplify the code (once you are comfortable with them)</p> <p>Functions that iterate over values usually treat a string as a sequence of characters.</p>"},{"location":"thinking-functionally/lazy-evaluation/","title":"Lazy Evaluation","text":"<p>Fixme work in progress</p> <p>In the most basic way possible, laziness is the ability to evaluate an expression only when it's actually needed.  Taken further, laziness is also evaluating an expression only to the extent required.</p>"},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-definition","title":"Laziness in definition","text":""},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-evaluation","title":"Laziness in evaluation","text":""},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-partial-evaluation","title":"Laziness in partial evaluation","text":"<p>Clojure is not entirely lazy, only the majority of sequence operations like map, reduce, filter or repeatedly are lazy evaluated.</p> <p>The most common use of laziness are infinite lists or streams. For example, we could define a list of all prime numbers. In case you didn't know, that's a lot of prime numbers (infinitely many).</p> <p>If we would define such list in a language like C++ or Python then the language would try to calculate all prime numbers immediately, which would run literally forever.</p> <p>If we define such list in Haskell or Clojure, then nothing is calculated just yet. As a matter of fact we could happily print out the first 1000 prime numbers from that list without running into a problem. Again, because lazy evaluation only calculates what is really needed, and nothing more.</p>"},{"location":"thinking-functionally/lazy-evaluation/#laziness-in-number-calculation-ratio-type","title":"Laziness in number calculation - Ratio type","text":"<p>Dividing an integer value by another results in a Ratio type if the result would otherwise result in a decimal number.  Clojure only partially evaluates this expression.</p> <pre><code>(/ 22 7)\n</code></pre> <p>We can also just express a value as a ratio.  This works because of the prefix notation of Clojure</p> <pre><code>22/7\n</code></pre> <p>The laziness can be overridden by specifying a precision, eg coercing the result into a specific type</p> <pre><code>(/  22 7.0)\n(double (/ 22 7))\n(float (/ 22 7))\n</code></pre>"},{"location":"thinking-functionally/lazy-evaluation/#making-something-lazy","title":"Making something lazy","text":"<p>The <code>range</code> function returns a sequence of numbers limited by any arguments given when calling the range function.</p> <p>Calling the range function without arguments will force an infinite sequence of numbers to be generated, quickly resulting in an out of memory error in the heap.</p> <p>Instead, we can either pass arguments to the range function that limit the sequence size or wrap the range function in another function</p> <pre><code>(take 7 (range))\n</code></pre> <p>The <code>take</code> function defines how much of a sequence that <code>range</code> should generate.  So we can call range without arguments and it will generate only those numbers in the sequence as specified by <code>take</code>.</p>"},{"location":"thinking-functionally/lazy-evaluation/#references","title":"References","text":"<ul> <li>Being lazy in Clojure - lazily generating monsters</li> </ul>"},{"location":"thinking-functionally/list-comprehension/","title":"List Comprehension","text":"<p>In general terms, list comprehensions should:</p> <ul> <li>be distinct from (nested) for loops and the use of map &amp; filter functions within the syntax of the language.</li> <li>return either a list or an iterator (an iterating being something that returns successive members of a collection, in order),</li> </ul> <p>In Clojure, list comprehension is via the <code>for</code> function.  This is different to the for in other languages as you will see.</p> <pre><code>(for [number [1 2 3]] (* number 2))\n</code></pre> <p>The <code>for</code> function should be read as follows:</p> <p>\"for each number in the collection [1 2 3], apply the function (* number 2)\"</p> <p>Couldn't we just do this with map?  Yes, we could.</p> <pre><code>(map #(* % 2) [1 2 3])\n</code></pre> <p>So why do we need <code>for</code> function?  It really shows its value when you are working with multiple collections</p> <pre><code>(for [number [1 2 3]\n      letter [:a :b :c]]\n  (str number letter))\n</code></pre> <p>Again we could use <code>map</code> function for this as follows</p> <pre><code>(mapcat (fn [number] (map (fn [letter] (str number letter)))))\n</code></pre> <p>So with the <code>for</code> function we can do the same calculation with much easier code to reason about.</p>"},{"location":"thinking-functionally/list-comprehension/#filtering-results-with-predicates","title":"Filtering results with predicates","text":"<p>With the <code>for</code> function we can add a filter on the results by using a predicate, to test if a condition is true or false.  Any values that meet the condition as true are returned, values that are false are omitted.</p> <pre><code>(for [x (range 10) :when (odd? x)] x)\n\n(for [x (range 10) :while (even? x)] x)\n</code></pre> <p>To do this kind of filtering with maps would be possible, however the code would be harder for humans to parse and understand.</p> <p>Note Create a 3-tumbler combination padlock, with each tumbler having a range of 0 to 9. Count the number of possible combinations.  Then add a predicate that filters out some of the combinations</p> <p>Lets just model all the possible combinations</p> <pre><code>(for [tumbler-1 (range 10)\n      tumbler-2 (range 10)\n      tumbler-3 (range 10)]\n [tumbler-1 tumbler-2 tumbler-3])\n</code></pre> <p>Now lets count the combinations</p> <pre><code>(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)]\n         [tumbler-1 tumbler-2 tumbler-3]))\n</code></pre> <p>Now add a predicate using <code>:when</code> to filter out the combinations that do not match.</p> <pre><code>(count (for [tumbler-1 (range 10)\n             tumbler-2 (range 10)\n             tumbler-3 (range 10)\n             :when (or (= tumbler-1 tumbler-2)\n                       (= tumbler-2 tumbler-3)\n                       (= tumbler-3 tumbler-1))]\n         [tumbler-1 tumbler-2 tumbler-3]))\n</code></pre> <p>Note Create a 2 character prefix for tickets, using capital letters from the English alphabet.  However, exclude I and O as they can be mistaken for numbers</p> <p>Lets just model all the possible combinations</p> <pre><code>(for [letter-1 capital-letters\n      letter-2 capital-letters\n      :when (and (not (blacklisted letter-1))\n                 (not (blacklisted letter-2)))]\n  (str letter-1 letter-2))\n</code></pre>"},{"location":"thinking-functionally/managing-state-changes/","title":"Managing state changes","text":""},{"location":"thinking-functionally/map-with-partial/","title":"map with partial","text":"<p>Lets look at different ways we can map functions over collections with <code>partial</code></p> <p>We can map over a collection of words and increment them by writing an anonymous function.</p> <pre><code>(map (fn [animal] (str animal \"s\")) [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre> <p>The anonymous function has a terse form, that removes the boiler plate function definition <code>(fn [])</code>, allowing definition of only the body of a function.</p> <p><code>%</code> represents a single argument passed to the function.  The <code>%</code> syntax also supports numbers where there are multiple arguments, e.g. <code>%1</code>, <code>%2</code> for the first and second arguments.  <code>%&amp;</code> represents all other arguments and is the same as <code>(fn [&amp; args])</code> or <code>(fn [arg1 &amp; args])</code>.</p> <p>The <code>#</code> character tells the Clojure reader that this is the macro form of a function definition and expands the code to the full form before executing.</p> <pre><code>(map #(str % \"s\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre>"},{"location":"thinking-functionally/map-with-partial/#hintwhen-to-use-the-terse-form-of-anonymous-function","title":"Hint::When to use the terse form of anonymous function","text":"<p>The terse form is often used with higher order functions, as an argument to a function. If the body of the function is simple to comprehend, then the terse form of anonymous function definition is appropriate.  When the body of a function is more complex, then consider using a separate <code>defn</code> function definition.</p>"},{"location":"thinking-functionally/map-with-partial/#returning-a-vector-instead-of-a-sequence","title":"Returning a Vector instead of a sequence","text":"<p>The <code>map</code> function returns a lazy sequence. This is very useful for large data sets.</p> <p><code>mapv</code> is an eager version of map that returns the result as a vector.  This is useful when you require random access lookup in real time.  <code>mapv</code> can also be used to return an eager result if laziness is not required.</p> <pre><code>(mapv #(str % \"s\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n</code></pre>"},{"location":"thinking-functionally/map-with-partial/#hintlists-and-vectors-does-it-matter","title":"Hint::Lists and vectors - does it matter?","text":"<p>Some functions in <code>clojure.core</code> will return a sequence using the list syntax, even if the arguments given are vectors.  Most of the time this is not important, as Clojure considers values rather than constructs for most of its functions. For example, <code>(= (\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\") [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])</code> is true as the values are compared rather than the type of container (list, vector)</p>"},{"location":"thinking-functionally/map-with-partial/#using-conditionals","title":"Using conditionals","text":"<p>Adding sheep as an element raises a problem, as the plural of sheep is sheep.</p> <p>Using a conditional, a test can be added to determine if a name should be made plural</p> <p>First lets abstract out the anonymous function to a shared function using <code>defn</code></p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (str string \"s\"))\n</code></pre> <p><code>def</code> will bind a name to our collection of animals</p> <pre><code>(def animals [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\"])\n\n(map pluralise animals)\n</code></pre> <p>The <code>if</code> function included a conditional test.  If that test is true the next expression is evaluated.  If the test is false, the second expression is evaluated.</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (if (= animal \"sheep\")\n    animal\n    (str animal \"s\")))\n\n(map pluralise animals)\n</code></pre> <p>There are several animals that do not have a plural form.  Rather than make a complicated test, a collection of animals that are not plural can be defined.</p> <pre><code>(def non-plural-words [\"deer\" \"sheep\" \"shrimp\" ])\n\n(defn pluralise\n  \"Pluralise a given string value\"\n  [animal]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n\n(def animals [\"pig\" \"cow\" \"goat\" \"cat\" \"dog\" \"rabbit\" \"sheep\" \"shrimp\" \"deer\"])\n\n(map pluralise animals)\n</code></pre> <p>To keep the function pure, we should pass the non-plural-words as an argument</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [animal non-plural-words]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n</code></pre> <p>Using the terse form of the anonymous function, <code>#()</code>, call the pluralise function with two arguments.  <code>map</code> will replace the <code>%</code> character with an element from the animals collection for each element in the collection.</p> <pre><code>(map #(pluralise % non-plural-words) animals)\n</code></pre> <p>The <code>partial</code> function can be used instead of creating an anonymous function, removing the need for more custom code.  The order of the arguments must be swapped for <code>partial</code> to call <code>pluralise</code> correctly</p> <pre><code>(defn pluralise\n  \"Pluralise a given string value\"\n  [non-plural-words animal]\n  (if (some #{animal} non-plural-words)\n    animal\n    (str animal \"s\")))\n</code></pre> <p>Now we can call pluralise by wrapping it as a partial function.</p> <p>The argument that is the non-plural-words is constant, its the individual elements of animals I want to get out via map.  So when map runs it gets an element from the animals collection and adds it to the call to pluralise, along with non-plural-words</p> <pre><code>(map (partial pluralise non-plural-words) animals)\n</code></pre> <p>Using partial here is like calling <code>(pluralise non-plural-words ,,,)</code> but each time including an element from animals where the <code>,,,</code> is.</p>"},{"location":"thinking-functionally/map-with-partial/#learning-at-the-repl","title":"Learning at the REPL","text":"<p>At first I was getting incorrect output, <code>[\"deer\" \"sheep\" \"shrimp\"]</code>, then I realised that it was returning the non-plural-words instead of pluralised animals.  The arguments from the partial function were being sent in the wrong order.  So I simply changed the order in the pluralise function and it worked.</p> <p>I checked this by adding some old-fashioned print statement.</p> <pre><code>(defn pluralise-wrong-argument-order\n  \"Pluralise a given string value\"\n  [animal non-plural-words ]\n  (if (some #{animal} non-plural-words)\n    (do\n      (println (str animal \" its true\"))\n      animal)\n    (do\n      (println (str animal \" its false\"))\n      (str animal \"s\"))))\n</code></pre>"},{"location":"thinking-functionally/partial-functions/","title":"Currying &amp; Partial Functions","text":"<p>Clojure does not support automatic currying, (+3) would result in applying + to 3, resulting with number 3 instead of a function that adds 3 as in Haskell. Therefore, in Clojure we use partial that enables the equivalent behavior.</p> <pre><code>(defn sum\n  \"Sum two numbers together\"\n  [number1 number2]\n  (+ number1 number2))\n\n(sum 1 2)\n;; =&gt; 3\n</code></pre> <p>If you try and evaluate <code>sum</code> with a single value then you get an arity exception</p> <pre><code>(sum 1)\n;; =&gt; clojure.lang.ArityException\n;; =&gt; Wrong number of args (1) passed to: functional-concepts/sum\n</code></pre> <p>If we did need to call sum with fewer than the required arguments, for example if we are mapping sum over a vector, then we can use partial to help us call the sum function with the right number of arguments.</p> <p>Lets add the value 2 to each element in our collection</p> <pre><code>(map (partial sum 2) [1 3 5 7 9])\n</code></pre>"},{"location":"thinking-functionally/partial-functions/#using-functions-on-more-arguments-than-they-can-normally-take","title":"Using functions on more arguments than they can normally take","text":"<p>The <code>reduce</code> function can only work on a single collection as an argument (or a value and a collection), so an error occurs if you wish to reduce over multiple collections.</p> <pre><code>(reduce + [1 2 3 4])\n;; =&gt; 10\n\n(reduce + [1 2 3 4] [5 6 7 8])\n;; returns an error due to invalid arguments\n</code></pre> <p>However, by using partial we can take one collection at once and return the result of reduce on each of those collections.</p> <pre><code>(map (partial reduce +) [[1 2 3 4] [5 6 7 8]])\n</code></pre> <p>In the above example we map the partial reduce function over each element of the vector, each element being a collection.</p>"},{"location":"thinking-functionally/partial-functions/#using-partial-to-set-a-default-value","title":"Using partial to set a default value","text":"<p>We can use the partial function to create a default message that can be just given just the custom part.  For example, if we want to have a default welcome message but include a custom part to the message at the end.</p> <p>First we would define a function that combines parts of the message together.</p> <pre><code>(defn join-strings\n  \"join one or more strings\"\n  [&amp; args]\n  (apply str args))\n</code></pre> <p>The [&amp; args] argument string says take all the arguments passed and refer to them by the name args.  Its the &amp; character that has the semantic meaning, so any name after the &amp; can be used, although args is common if there is no domain specific context involved.</p> <p>We can simply call this function with all the words of the message.</p> <pre><code>(join-strings \"Hello\" \" \" \"Clojure\" \" \" \"world\")\n;; \u21d2 \"Hello Clojure world\"\n</code></pre> <p>Now we define a name called <code>wrap-message</code> that can be used to wrap the start of our message.  This name binds to a partial function call to <code>join-strings</code> which send that function the default message and any custom message you add when evaluate <code>wrap-message</code></p> <pre><code>(def wrap-message (partial join-strings \"Hello Clojurians in \"))\n\n(wrap-message)\n;; \u21d2 \"Hello Clojurians in \"\n\n(wrap-message \"London\")\n ;; =&gt; \"Hello Clojurians in London\"\n</code></pre>"},{"location":"thinking-functionally/partial-functions/#currying-in-clojure","title":"Currying in clojure","text":"<p>Currying is the process of taking some function that accepts multiple arguments, and turning it into a sequence of functions, each accepting a single argument.  Or put another way, to transform a function with multiple arguments into a chain of single-argument functions.</p> <p>Currying relies on having fixed argument sizes, whereas Clojure gets a lot of flexibility from variable argument lengths (variable arity).</p> <p>Clojure therefore has the partial function gives results similar to currying, however the <code>partial</code> function also works with variable functions.</p> <p><code>partial</code> refers to supplying some number of arguments to a function, and getting back a new function that takes the rest of the arguments and returns the final result</p> <p>One advantage of <code>partial</code> is to avoid having to write your own anonymous functions</p>"},{"location":"thinking-functionally/partial-functions/#useful-references","title":"Useful references","text":"<ul> <li>Partial function applications for humans</li> </ul>"},{"location":"thinking-functionally/pattern-matching/","title":"Pattern matching","text":"<p>Fixme work in progress</p>"},{"location":"thinking-functionally/pattern-matching/#regular-expression","title":"Regular Expression","text":""},{"location":"thinking-functionally/pattern-matching/#destructuring","title":"Destructuring","text":""},{"location":"thinking-functionally/persistent-data-structures/","title":"Persistent data structures","text":""},{"location":"thinking-functionally/polymorphism/","title":"Polymorphic function definitions","text":"<p>Polymorphic means many forms.</p> <p>The simplest example of polymorphism in Clojure is a function definition that acts differently based on the number of arguments passed.</p> <p>Usually you define a function with one set of arguments, either none <code>[]</code>, one <code>[one]</code> or many <code>[any number of args]</code>, using the basic syntax</p> <pre><code>(defn name\n\"I am the doc string to describe the function\"\n  [args]\n  (str \"define your behaviour here\"))\n</code></pre> <p>Instead of writing multiple functions with the same name that each take different numbers of arguments, you can use the following polymorphic syntax in Clojure</p> <pre><code>(defn name\n  \"I am the doc string to describe the function\"\n  ([]\n    (str \"behaviour with no args\"))\n  ([one]\n    (str \"behaviour with one arg\"))\n  ([one two &amp; args]\n    (str \"behaviour with multiple args\")))\n</code></pre> <p>Note Write a simple function called <code>i-am-polly</code> that returns a default message when given no arguments and a custom message when given a custom string as an argument</p> <pre><code>(defn i-am-polly\n  ([] (i-am-polly \"My name is polly\"))\n  ([message] (str message)))\n\n(i-am-polly)\n(i-am-polly \"I call different behaviour depending on arguments sent\")\n</code></pre>"},{"location":"thinking-functionally/pure-functions/","title":"Pure functions","text":"<p>A function is considered pure if does not side effects or is affected by side causes.  A pure function does not change any other part of the system and is not affected by any other part of the system.</p> <p>When you pass arguments to a function and that function returns a value without interacting with any other part of the system, then that function is considered pure.</p> <p>Should something from outside a function be allowed to affect the result of evaluating a function, or if that function be allowed to affect the outside world, then its an impure function.</p> <p></p> <p>So lets look at a simple code example</p> <pre><code>(defn add-numbers [number1 number2]\n  (+ number1 number2))\n\n(add-numbers 1 2)\n</code></pre> <p>Lets look at each line of this suggested answer</p> <pre><code>;; function takes 2 arguments\n;; function uses both arguments for result\n(defn add-numbers [number1 number2]\n  (+ number1 number2))\n\n;; specific values are passed as arguments\n(add-numbers 1 2)\n</code></pre>"},{"location":"thinking-functionally/pure-functions/#notewrite-a-pure-function-that-adds-two-numbers-together","title":"Note::Write a pure function that adds two numbers together ?","text":""},{"location":"thinking-functionally/pure-functions/#an-example-with-map","title":"An example with map","text":"<p>Note Define a collection called numbers and write a named function that increments each number of the numbers collection. Is your function pure or impure ?</p> <pre><code>(def numbers '(5 4 3 2 1))\n\n(defn increment-numbers []\n  (map inc numbers))\n\n(increment-numbers)\n</code></pre> <p>The function takes no arguments and is pulling in a value from outside the function.  This is a trivial example, but if all your code is like this it would be more complex.  If the value pointed to by <code>numbers</code> is mutable and changes before the <code>increment-numbers</code> function is called then you will get different results.</p> <p>Here is a Pure function example</p> <pre><code>(def numbers '(5 4 3 2 1))\n\n(defn increment-numbers [number-collection]\n  (map inc number-collection))\n\n(increment-numbers numbers)\n</code></pre> <p>In this example we are explicitly passing the <code>numbers</code> collection to the function.  The function works on passed value and returns a predictable result.</p>"},{"location":"thinking-functionally/recursion-polymorphism/","title":"Recursion &amp; Polymorphism","text":"<p>Fixme work in progress</p> <p>The following <code>sum</code> function will calculate the value of adding all the elements in a collection.  You can alter the results by adding a starting value to the calculation as a second argument when calling <code>sum</code></p> <pre><code>(defn sum\n  ([vals] (sum vals 0))\n  ([vals accumulating-total]\n    (if (empty? vals)\n      accumulating-total\n      (sum (rest vals) (+ (first vals) accumulating-total)))))\n\n(sum [2 7 9 11 13])\n(sum [1])\n(sum [2 7 9 11 13] 9)\n</code></pre> <p>Rather than duplicate the calculation, the behaviour of calling <code>sum</code> with just a collection simply calls <code>sum</code> again, this time passing a starting value of zero.</p>"},{"location":"thinking-functionally/recursion/","title":"Recursion","text":"<p>Fixme work in progress</p> <p>Recursion is used greatly in Clojure to iterate through data and as anything can be treated as data in Clojure you can understand why.</p> <p>The constructs available in Clojure for recursion include</p> <ul> <li><code>loop</code> and <code>recur</code></li> <li>Named function that calls itself</li> <li><code>map</code>, <code>reduce</code>, <code>filter</code>, <code>remove</code>, etc.</li> <li><code>for</code></li> </ul>"},{"location":"thinking-functionally/recursion/#recursively-calling-the-same-function","title":"Recursively calling the same function","text":"<p>Lets iterate though a collection using recursion by writing a function that calls itself</p> <pre><code>(defn recursively-use-a-collection [collection]\n  (println (first collection))\n  (if (empty? collection)\n    (print-str \"no more values to process\")\n    (recursively-use-a-collection  (rest collection))))\n\n(recursively-use-a-collection [1 2 3])\n</code></pre> <p>Lets take this recursive approach to create a function that can tell us the length of a collection (list or vector)</p> <p>We define a function that takes a collection of an argument.  The collection is tested to see if it is empty and if so a zero value is returned.  If the collection is not empty, then we</p> <pre><code>(defn length [collection]\n  (if (empty? collection)\n    0\n    (+ 1 (length (rest collection)))))\n;; =&gt; #'clojure-through-code.01-basics/length\n</code></pre> <p>If we call the <code>length</code> function with an empty collection, then the <code>empty?</code> condition will return true and the <code>if</code> expression will evaluate the first expression, 0, returning 0.</p> <pre><code>(length [])\n;; =&gt; 0\n</code></pre> <p>If we call the <code>length</code> function with a collection containing 3 values, then the <code>empty?</code> function will return <code>false</code> and the <code>if</code> function will evaluate the second expression.</p> <p>The second expression starts with a simple counter, using the <code>+</code> function and the value one</p> <pre><code>(length [0 1 2])\n;; =&gt; 3\n</code></pre> <pre><code>(+ 1 (length [1 2]))\n(+ 1 (+ 1 (length [2])))\n(+ 1 (+ 1 (+ 1 (length []))))\n(+ 1 (+ 1 (+ 1 0)))\n\n(length (range 24))\n;; =&gt; 24\n</code></pre> <p>(defn length [collection]   (kk))</p>"},{"location":"thinking-functionally/recursion/#further-recursion-examples","title":"Further recursion examples","text":"<p>Other functions to consider</p> <ul> <li>every</li> <li>accumulating / accumulative</li> <li>keep</li> </ul>"},{"location":"thinking-functionally/sequence-abstractions/","title":"Sequence abstraction","text":"<p>Fixme work in progress</p> <pre><code>(first '(1 2 3 4 5))\n(rest '(1 2 3 4 5))\n(last '(1 2 3 4 5))\n</code></pre> <pre><code>(defn nth [items n]\n (if (= n 0)\n   (first items)\n   (recur (rest items) (- n 1))))\n\n(define squares '(0 1 4 9 16 25))\n\n(nth squares 3)\n</code></pre>"},{"location":"thinking-functionally/sequences/","title":"Sequences","text":"<p>Fixme work in progress</p> <p>Data structures can be built by combining functions</p> <pre><code>(cons 1 (cons 2  (cons 3  (cons 4  nil))))\n</code></pre> <pre><code>(-&gt;&gt;\n nil\n (cons 4)\n (cons 3)\n (cons 2)\n (cons 1))\n</code></pre>"},{"location":"thinking-functionally/side-effects/","title":"Side effects","text":"<p>A side effect is something that creates a change outside of the current code scope, or something external that affects the behaviour or result of executing the code in the current scope.</p>"},{"location":"thinking-functionally/side-effects/#nondeterministic-the-complexity-iceberg","title":"Nondeterministic - the complexity iceberg","text":"<p>When you have side effects, you cannot reason accurately about a piece of the code.</p> <p>In order to understand a piece of code you must look at all possible side effects created in all lines of code to ensure you fully understand the result of executing your code.</p> <p>With side effects in your system, complexity is hidden, causing a far greater risk of a dangerous situation.</p>"},{"location":"thinking-functionally/side-effects/#side-causes-side-effects","title":"Side causes - side effects","text":"<p>You can think about these effects is in two specific areas, Side Causes and Side Effects</p> <ul> <li> <p>Side Causes - are where other pieces of code (function) or state change affects the behaviour of a function.</p> </li> <li> <p>Side Effects - are where the current code (function) affects the rest of the system</p> </li> </ul> <p></p>"},{"location":"thinking-functionally/side-effects/#hintside-causes-term","title":"Hint::Side Causes term","text":"<p>The term of side causes was coined by Kris Jenkins in the superb article What is Functional Programming?</p>"},{"location":"thinking-functionally/tail-recursion/","title":"Tail recursion","text":"<p>Fixme work in progress</p> <p>If we generate a very large collection we run the risk of blowing our heap space.  For example we could use range to generate a very large collection, say a vector containing 10 billion values</p> <p>Don't try this example below</p> <pre><code>(vec (range 0 9999999999))\n;; this will crash after a short while as it will use up all your heap space\n</code></pre> <p>Using tail call optimisation (tail recursion) allows us to reuse a memory location when we call a function recursively.  This tail recursion is not part of the underlying Java Virtual Machine (JVM), so instead Clojure has a specific function called <code>recur</code></p> <p>The <code>recur</code> function allows the processing of a very large data set without blowing the heap space because the memory space will be reused.</p> <p>The <code>recur</code> function must be the last expression in order to work.</p> <pre><code>(defn sum\n  ([vals] (sum vals 0))\n  ([vals accumulating-total]\n   (if (empty? vals)\n     accumulating-total\n     (recur (rest vals) (+ (first vals) accumulating-total)))))\n\n(sum (vec (range 0 9999999)))\n</code></pre>"},{"location":"thinking-functionally/threading-macros/","title":"Threading macros","text":"<p>The thread-first <code>-&gt;</code> and thread-last <code>-&gt;&gt;</code> macros allow Clojure code to be written in a more sequential style and with a more terse syntax.  This can sometimes make code easier to understand by humans.</p> <p>Using the thread-first macro, <code>-&gt;</code>, the result of the first evaluation is passed as the first argument to the next function and so on.</p> <p>```clojure (-&gt;  (clojure.string/lower-case \"HELLO\")  (str \", Clojure world\")) <pre><code>The value hello is converted to lower case and that result is passed as the first argument to the next function.  The string function is then evaluated with this new argument and the final \"hello, Clojure world\" string is returned as the result.\n\n  The thread-last macro `-&gt;&gt;` passes the result of the first evaluation as the **last argument** to the next expression.\n\n```clojure\n(-&gt;&gt;  \" this\"\n (str \" is\")\n (str \" backwards\"))\n</code></pre></p>"},{"location":"thinking-functionally/threading-macros/#hintparens-optional","title":"Hint::Parens optional","text":"<p>function calls that only take one argument, the one passed by earlier expressions, can be included in the threading macro code without the surrounding <code>()</code> parens.</p>"},{"location":"thinking-functionally/threading-macros/#reading-clojure-code","title":"Reading Clojure code","text":"<p>To read Clojure it is common to start from the inside out, as this is how the Clojure reader also works.  This style is inherited from Lisp of which Clojure is an implementation.</p> <p>The following code is written in classic Lisp style.</p> <pre><code>(reverse\n  (sort-by val (frequencies\n                 (remove common-english-words\n                   (map #(clojure.string/lower-case %)\n                        (re-seq #\"[a-zA-Z0-9|']+\"\n                                (slurp book.txt)))))))\n</code></pre> <p>Reading inside out:</p> <ol> <li>slurp in the contents of the book.txt file, converting it to a string.</li> <li>use a regular expression to create a new sequence where the book is a sequence of individual strings for each word.</li> <li>convert each string in the sequence by mapping the lower-case function over each element of the sequence.</li> <li>remove common english words such as the and and from the sequence.</li> <li>count how many times each word occurs and pair the string with its frequency in the book.</li> <li>reverse the order of the sequence by the value of frequency, so the most used word is at the start of the sequence.</li> </ol> <p>This function uses the var <code>common-english-words</code> which is defined as:</p> <pre><code>(def (set\n       (clojure.string/split (slurp \"common-english-words.txt\") #\",\" )))\n</code></pre> <p>This takes a comma separated file of words and splits them.  The words are put into a set so only one instance of each word is included.</p>"},{"location":"thinking-functionally/threading-macros/#rewriting-the-code-with-threading-macros","title":"Rewriting the code with threading macros","text":"<pre><code>(-&gt;&gt; (slurp book.txt)\n     (re-seq #\"[a-zA-Z0-9|']+\" ,,,)\n     (map #(clojure.string/lower-case %))\n     (remove common-english-words)\n     frequencies\n     (sort-by val)\n     reverse)\n</code></pre> <p><code>frequencies</code> and <code>reverse</code> only take one argument, so they do not require surrounding <code>()</code> inside the threading macro.</p> <p>The common-english-words var is fairly easy to read, so probably doesn't need to be written using a threading macro, however, for completeness here is a thread-first example.</p> <pre><code>(def common-english-words\n  (-&gt; (slurp \"common-english-words.txt\")\n      (clojure.string/split #\",\")\n      set))\n</code></pre>"},{"location":"thinking-functionally/threading-macros/#hintmacroexpand","title":"Hint::Macroexpand","text":"<p>use <code>macroexpand-1</code> around the threading macro code to show resulting lisp style Clojure code.  Clojure editors also provide evaluation functions that will macroexpand.</p>"},{"location":"thinking-functionally/transducers/","title":"Transducers","text":"<p>Transducers provide an efficient way to transform values from a collection or stream of data, eg. core.async channel, java.jdbc database query (0.7.0 upward) or a network stream etc.</p> <p>Transformations are applied directly to a stream of data without first creating a collection.</p> <p>Multiple transducers are composed into a single transforming function, walking the data elements only once and without the need for intermediate collections.  </p> <p>One Transducer benefit is to allow the design to switch from a seq-based implementation to a core.async implementation using channels</p> <p>Transducers: Clojure.org Transducer use cases </p> <p>Basics Transducer walkthrough</p> <p>Simple examples of Clojure Transducers</p> <p> </p> <p> </p>"},{"location":"thinking-functionally/transducers/#evolving-design","title":"Evolving design","text":"<p>Each element of the data collection is acted upon by a composition of each transducer in an expression, making them more efficient than a applying one expression after another (e.g. as with a thread macro or composed list expressions). </p> <p>Transducers provide benefits like lazy evaluation and alternative performance trade-offs.</p> <p>Nested calls</p> <pre><code>(reduce + (filter odd? (map #(+ 2 %) (range 0 10))))\n</code></pre> <p>Functional composition</p> <pre><code>(def xform\n  (comp\n    (partial filter odd?)\n    (partial map #(+ 2 %))))\n  (reduce + (xform (range 0 10)))\n</code></pre> <p>Thread macro</p> <pre><code>    (defn xform [xs]\n      (-&gt;&gt; xs\n           (map #(+ 2 %))\n           (filter odd?)))\n    (reduce + (xform (range 0 10)))\n</code></pre> <p>Transducer</p> <pre><code>(def xform\n  (comp\n    (map #(+ 2 %))\n    (filter odd?)))\n(transduce xform + (range 0 10))\n</code></pre> <p>The order of combinators in a transducer is the same as a thread macro (natural order). </p>"},{"location":"thinking-functionally/transducers/#coreasync","title":"core.async","text":"<p>Transducers were introduced into the Clojure language to provide a common abstraction to avoid re-implmentation of clojure.core transformation functions specific to core.async.</p> <p>in a large part to support processing data to and from a core.async channel.</p> <p>The Clojure maintainers discovered they were re-implementing filter, map, partition, etc. on core.async and realized it would be better to have an abstraction for the transforms independent of the source and destination of data.</p> <p>The xform can be used with an core.async channel</p> <p>Transducer with core.async</p> <pre><code>(chan 1 xform)\n</code></pre> <p>an optional arg when creating a channel, causing a transform to be applied to all data that goes through the channel</p>"},{"location":"thinking-functionally/transducers/#database-queries","title":"Database queries","text":"<p>Typical database access involves passing in functions to transform rows and process the transformed result set</p> <p><code>java.jdbc</code> 0.7.0-beta1 onwards can also apply transducers to \u201creducible queries\u201d (and reducible result sets).</p> <p>Create a reducible query which is passed to transforming function, e.g. reducers, transducers, plain ol\u2019 <code>reduce</code> and <code>into</code> etc </p>"},{"location":"thinking-functionally/transducers/#simplified-description","title":"Simplified description","text":"<p>Transducers are recipes what to do with a sequence of data without knowledge what the underlying sequence is (how to do it). It can be any seq, async channel or maybe observable.</p> <p>They are composable and polymorphic.</p> <p>The benefit is, you don't have to implement all standard combinators every time new data source is added. Again and again. As resulting effect you as user are able to reuse those recipes on different data sources.</p> <p>https://stackoverflow.com/questions/26317325/can-someone-explain-clojure-transducers-to-me-in-simple-terms</p> Work In Progress, sorry <p>A very messy brain dump of ideas to tidy up. Pull requests are welcome</p> <p>Clojure.core functions such as map and filter are lazy, however they also generate containers for lazy values when chained together. </p> <p>Without holding onto the head of the collection, large lazy sequences aren't created but intermediate abstractions are still created for each lazy element.</p>"},{"location":"thinking-functionally/transducers/#reducing-functions","title":"Reducing functions","text":"<p>Reducing functions are those that take two arguments: </p> <ul> <li>a result so far </li> <li>an input. </li> </ul> <p>The reducing function returns a new result (so far). </p> <p>For example +: With two arguments, you can think of the first as the result so far and the second as the input.</p> <p>A transducer could now take the + function and make it a twice-plus function (doubles every input before adding it). This is how that transducer would look like (in most basic terms):</p> <p>Reducing function</p> <pre><code>(defn double\n  [rfn]\n  (fn [r i]\n    (rfn r (* 2 i))))\n</code></pre> <p>For illustration substitute rfn with + to see how + is transformed into twice-plus:</p> <p>Reducing function - twice plus</p> <pre><code>(def twice-plus ;; result of (double +)\n  (fn [r i]\n    (+ r (* 2 i))))\n\n(twice-plus 1 2)  ;-&gt; 5\n(= (twice-plus 1 2) ((double +) 1 2)) ;-&gt; true\n</code></pre> <p>Calling the reducing function</p> <pre><code>(reduce (double +) 0 [1 2 3])\n\n;; =&gt; 12\n</code></pre> <p>Reducing functions returned by transducers are independent of how the result is accumulated because they accumulate with the reducing function passed to them. </p> <p><code>conj</code> takes a collection and a value and returns a new collection with that value appended.</p> <pre><code>(reduce (double conj) [] [1 2 3])\n;; =&gt; [2 4 6]\n</code></pre> <p>Transducers are independent of the kind of data is passed.</p> <p>optimisation goes beyond eliminating intermediate streams; it is possible to perform operations in parallel.</p>"},{"location":"thinking-functionally/transducers/#pmap","title":"pmap","text":"<p>Use <code>pmap</code> when mapping an expensive function over a sequence, making the operation parallel.  No other changes to the code are required. </p> <p>Transducers will still be faster if the pmap function creates intermedicate data structures.</p> <p>A transducer clear definition is here:</p> <p>Transducers are a powerful and composable way to build algorithmic transformations that you can reuse in many contexts.</p>"},{"location":"thinking-functionally/transducers/#reducing-functions_1","title":"Reducing functions","text":"<p>Population a local Village</p> <p>The  <pre><code>(def village\n  [{:home :north :family \"smith\" :name \"sue\" :age 37 :sex :f :role :parent}\n   {:home :north :family \"smith\" :name \"stan\" :age 35 :sex :m :role :parent}\n   {:home :north :family \"smith\" :name \"simon\" :age 7 :sex :m :role :child}\n   {:home :north :family \"smith\" :name \"sadie\" :age 5 :sex :f :role :child}\n\n   {:home :south :family \"jones\" :name \"jill\" :age 45 :sex :f :role :parent}\n   {:home :south :family \"jones\" :name \"jeff\" :age 45 :sex :m :role :parent}\n   {:home :south :family \"jones\" :name \"jackie\" :age 19 :sex :f :role :child}\n   {:home :south :family \"jones\" :name \"jason\" :age 16 :sex :f :role :child}\n   {:home :south :family \"jones\" :name \"june\" :age 14 :sex :f :role :child}\n\n   {:home :west :family \"brown\" :name \"billie\" :age 55 :sex :f :role :parent}\n   {:home :west :family \"brown\" :name \"brian\" :age 23 :sex :m :role :child}\n   {:home :west :family \"brown\" :name \"bettie\" :age 29 :sex :f :role :child}\n\n   {:home :east :family \"williams\" :name \"walter\" :age 23 :sex :m :role :parent}\n   {:home :east :family \"williams\" :name \"wanda\" :age 3 :sex :f :role :child}])\n</code></pre></p> <p>Define a reducing expression to return the number of children in the village.</p> <pre><code>(def children \n  (r/map #(if (= :child (:role %)) 1 0)))\n</code></pre> <p>Call the expression <pre><code>(r/reduce + 0 (children village))\n;;=&gt; 8\n</code></pre></p> <p>Using a transducer to add up all the mapped values</p> <p>create the transducers using the new arity for map that takes the function, no collection</p> <pre><code>(def child-numbers (map #(if (= :child (:role %)) 1 0)))\n</code></pre> <p>Use transduce (c.f r/reduce) with the transducer to get the answer <pre><code>(transduce child-numbers + 0 village)\n;;=&gt; 8\n</code></pre></p> <p>It is really powerful when taking subgroups in account, e.g to know how many children in the Brown Family</p> <p>Reducer to count children in Brown family</p> <p>Create the reducer to select members of the Brown family</p> <pre><code>(def brown-family-children\n  (r/filter #(= \"brown\" (string/lower-case (:family %)))))\n</code></pre> <p>compose a composite function to select the Brown family and map children to 1</p> <pre><code>(def count-brown-family-children \n  (comp ex1a-map-children-to-value-1 brown-family-children))\n</code></pre> <p>reduce to add up all the Brown children <pre><code>(r/reduce + 0 (ex2a-count-brown-family-children village))\n;;=&gt; 2\n</code></pre></p>"},{"location":"thinking-functionally/transducers/#references","title":"References","text":"<p>Transducers - Clojure next big idea</p>"},{"location":"using-data-structures/","title":"Using data structures","text":"<p>Data structures in Clojure are used to model information and data, within a particular namespace.  Functions are used to run behaviour over the data structures.</p> <p>Lets look at some of the common functions that are used in Clojure with data structures</p> <p>fixme the below content is work in progress, sorry.</p>"},{"location":"using-data-structures/#managing-return-values","title":"Managing Return values","text":"<p>If you run a function over a data structure, you may not always get back the type of value you want.  It easy to wrap a function around to give you the desired value type.</p> <p>Note Use the <code>str</code> function to get a string from person, rather than a set of characters</p> <pre><code>(first person)\n(rest person)\n\n(str (first person))\n\n;; How do we return the rest of the string as a string ?\n(str (rest person))\n(map str (rest person))\n(str (map str (rest person)))\n(apply str (rest person))\n</code></pre> <p>You can get the value of this map</p> <pre><code>(def luke {:name \"Luke Skywalker\" :skill \"Targeting Swamp Rats\"})\n(def darth {:name \"Darth Vader\"    :skill \"Crank phone calls\"})\n(def jarjar {:name \"JarJar Binks\"   :skill \"Upsetting a generation of fans\"})\n\n(get luke :skill)\n</code></pre>"},{"location":"using-data-structures/#immutability","title":"Immutability","text":"<p>When you use functions on data structures, although they can return a new value they do not change the original data structure.</p> <p>Lets define a name for a data structure</p> <pre><code>(def name1 [1 2 3 4])\n</code></pre> <p>when we evaluate that name we get the original data we set</p> <pre><code>name1\n</code></pre> <p>Now we use a function called conj to adds (conjoin) another number to our data structure</p> <pre><code>(conj name1 5)\n</code></pre> <p>This returns a new value without changing the original data structure</p> <pre><code>name1\n</code></pre> <p>We cant change the original data structure, it is immutable.  Once it is set it cant be changed. However, if we give a name to the result of changing the original data structure, we can refer to that new data structure</p> <pre><code>(def name2(conj name1 5))\n</code></pre> <p>Now name2 is the new data structure, but name1 remains unchanged</p> <pre><code>name2\nname1\n</code></pre> <p>So we cannot change the data structure, however we can achieve something that looks like we have changed it.  We can re-assign the original name to the result of changing the original data structure</p> <pre><code>(def name2(conj name1 5))\n</code></pre> <p>Now name1 and name2 are the same result</p> <pre><code>name2\nname1\n</code></pre> <p>An analogy</p> <p>You have the number 2.  If you add 1 to 2, what value is the number 2?</p> <p>The number 2 is still 2 no mater that you add 1 to it, however, you get the value 3 in return</p>"},{"location":"using-data-structures/#creating-new-data-structures","title":"Creating new data structures","text":"<p>Use concat to add lists or vectors together</p> <pre><code>(concat [1 2] '(3 4)) ; =&gt; (1 2 3 4)\n</code></pre> <p>Use filter, map to interact with collections</p> <pre><code>(map inc [1 2 3]) ; =&gt; (2 3 4)\n(filter even? [1 2 3]) ; =&gt; (2)\n</code></pre> <p>Use reduce to reduce them</p> <pre><code>(reduce + [1 2 3 4])\n; = (+ (+ (+ 1 2) 3) 4)\n; =&gt; 10\n</code></pre> <p>Reduce can take an initial-value argument too</p> <pre><code>(reduce conj [] '(3 2 1))\n; = (conj (conj (conj [] 3) 2) 1)\n; =&gt; [3 2 1]\n</code></pre> <p>Use cons to add an item to the beginning of a list or vector</p> <pre><code>(cons 4 [1 2 3]) ; =&gt; (4 1 2 3)\n(cons 4 '(1 2 3)) ; =&gt; (4 1 2 3)\n</code></pre> <p>Use conj to add an item to the beginning of a list, or the end of a vector</p> <pre><code>(conj [1 2 3] 4) ; =&gt; [1 2 3 4]\n(conj '(1 2 3) 4) ; =&gt; (4 1 2 3)\n</code></pre>"},{"location":"using-data-structures/applying-functions/","title":"Applying functions to data structures","text":"<p>Applying a functions behaviour to the elements of a data structure</p>"},{"location":"using-data-structures/destructuring/","title":"Destructuring","text":"<p>Destructuring is a form of pattern matching that is common in Clojure.  Destructuring allow you to pull out the specific elements from a collection.</p> <p>Destructuring is commonly used with the <code>let</code> method for creating local bindings (locally scoped names).</p> <pre><code>(let [[a b c &amp; d :as e] [1 2 3 4 5 6 7]]\n  [a b c d e])\n\n(let [[[x1 y1][x2 y2]] [[1 2] [3 4]]]\n  [x1 y1 x2 y2])\n\n;; with strings\n(let [[a b &amp; c :as str] \"asdjhhfdas\"]\n  [a b c str])\n\n;; with maps\n(let [{a :a, b :b, c :c, :as m :or {a 2 b 3}}  {:a 5 :c 6}]\n  [a b c m])\n</code></pre> <p>It is often the case that you will want to bind same-named symbols to the map keys. The :keys directive allows you to avoid the redundancy:</p> <pre><code>(let [{fred :fred ethel :ethel lucy :lucy} m] )\n</code></pre> <p>This can be written in a shorter form as follows:</p> <pre><code>(let [{:keys [fred ethel lucy]} m] )\n</code></pre> <p>As of Clojure 1.6, you can also use prefixed map keys in the map destructuring form:</p> <pre><code>(let [m {:x/a 1, :y/b 2}\n      {:keys [x/a y/b]} m]\n  (+ a b))\n</code></pre> <p>As shown above, in the case of using prefixed keys, the bound symbol name will be the same as the right-hand side of the prefixed key. You can also use auto-resolved keyword forms in the :keys directive:</p> <pre><code>(let [m {::x 42}\n      {:keys [::x]} m]\n  x)\n</code></pre>"},{"location":"using-data-structures/lazy-sequences/","title":"Lazy Sequences","text":"<p>Sequences are an interface for logical lists, which can be lazy.  \"Lazy\" means that a sequence can define an infinite series, like so:</p> <pre><code>(range 4)\n</code></pre> <p>If you evaluate <code>(range)</code> just by itself it will return an infinite number of integers, well at least until your computers memory space fills up.</p> <p>So we dont blow up our memory and just get the values we want we can use <code>range</code> in conjunction with other functions that define how many numbers we actually want.</p> <p>For example, if we just wanted the first four numbers from the infinite sequence of <code>range</code> we could specify that with the <code>take</code> function</p> <pre><code>(take 4 (range)) ;  (0 1 2 3)\n</code></pre> <p>Here the range function is being lazy, because it will only generate the first 4 numbers in its sequence.</p> <p>Clojure (and Lisps in general) often evaluate at the last possible moment, usually when they have been given more specific content.</p>"},{"location":"using-data-structures/mapping-data-structures/","title":"Mapping functions over data structures","text":"<p>Map allows you to work over one or more data sets, applying the function to each element of each of the data structures.</p> <p>When the data structures are of equal size, then the same sized data structure is returned.</p> <pre><code>(map + [1 2 3] [1 2 3])\n;; =&gt; (2 4 6)\n</code></pre> <p>If one data structure is smaller, then the function is only applied up to the last element of the smallest data structure.</p> <pre><code>(map + [1 2 3] [1 2])\n;; =&gt; (2 4)\n\n(map + [1 2 3] [1])\n;; =&gt; (2)\n\n(map + [1 2 3] [])\n;; =&gt; ()\n\n(map + [1 2 3])\n;; =&gt; (1 2 3)\n</code></pre> <p>Lets look at another example.  Here we have a pre-defined Fibonacci sequence up to the first 12 values.</p> <pre><code>(def fibonacci-sequence [1 2 3 5 8 13 21 34 55 89 144 278])\n</code></pre> <p>If we just want the first 10 values of the sequence, we can use the <code>take</code> function.</p> <pre><code>(take 10 fibonacci-sequence)\n;; =&gt; (1 2 3 5 8 13 21 34 55 89)\n</code></pre> <p>If we want a calculation using the values of the fibonacci-sequence then we can use <code>map</code> with a function.  In this case we are going to generate a range of Integer numbers from 0-9 using the function <code>range</code>.  That range of numbers is then multiplied element by element with the corresponding element in the fibonacci-sequence.</p> <pre><code>(map * (range 10) fibonacci-sequence)\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>So,</p> <ul> <li>0 times 1 is 0,</li> <li>1, times 2 is 2,</li> <li>2 times 3 is 6, etc.</li> </ul> <p>If we evaluate the previous expression part by part, its easier to see what is going on.  First lets evaluate the <code>fibonacci-sequence</code></p> <pre><code>(map * (range 10) [1 2 3 5 8 13 21 34 55 89 144 278])\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>Now lets evaluate the <code>(range 10)</code> function call</p> <pre><code>(map * (0 1 2 3 4 5 6 7 8 9) [1 2 3 5 8 13 21 34 55 89 144 278])\n;; =&gt; (0 2 6 15 32 65 126 238 440 801)\n</code></pre> <p>We can see the answer is the same, however by evaluating each part of the expression we get an exact view of what is going to happen with the <code>map</code> function.</p>"},{"location":"using-data-structures/sequences/","title":"Sequence abstractions","text":"<p>There are functions that work on all the built in data-structures in Clojure.</p> <p><code>first</code> <code>second</code> <code>rest</code> <code>cons</code></p>"},{"location":"using-data-structures/sequences/#practising-with-lists","title":"Practising with lists","text":"<p>Create a simple collection of developer events.  First use a list of strings, then try a map with keywords.  For each data structure, pull out some of the event details</p> <pre><code>(def developer-events-strings '(\"Devoxx UK\" \"Devoxx France\" \"Devoxx\" \"Hack the Tower\"))\n\n(def developer-events-strings2 (list \"Devoxx UK\" \"Devoxx France\" \"Devoxx\" \"Hack the Tower\"))\n\ndeveloper-events-strings\n\n(first developer-events-strings)\n\n(def developer-events-vector\n  [:devoxxuk :devoxxfr :devoxx :hackthetower] )\n</code></pre> <p>Using a Clojure Vector data structure is a more Clojure approach, especially when the vector contains keywords.  Think of a Vector as an Array, although in Clojure it is again immutable in the same way a list is.</p> <p>Create a slightly more involved data structure, holding more data around each developer events.  Suggest using a map, with each key being the unique name of the developer event.</p> <p>The details of each event (the value to go with the event name key) is itself a map as there are several pieces of data associated with each event name.</p> <pre><code>(def dev-event-details\n  {:devoxxuk     {:URL \"http://jaxlondon.co.uk\"\n                  :event-type \"Conference\"\n                  :number-of-attendees 700\n                  :call-for-papers true}\n   :hackthetower {:URL \"http://hackthetower.co.uk\"\n                  :event-type \"hackday\"\n                  :number-of-attendees 60\n                  :call-for-papers false}})\n</code></pre> <p>Lets call the data structure and see what it evaluates too, it should not be a surprise</p> <pre><code>dev-event-details\n</code></pre> <p>We can ask for the value of a specific key, and just that value is returned</p> <pre><code>(dev-event-details :devoxxuk)\n</code></pre> <p>In our example, the value returned from the :devoxxuk key is also a map, so we can ask for a specific part of that map value by again using its key</p> <pre><code>(:URL (dev-event-details :devoxxuk))\n</code></pre> <p>Define a simple data structure for stocks data using a vector of maps, as there will be one or more company stocks to track.</p> <p>Each map represents the stock information for a company.</p> <p>Get the value of the whole data structure by referring to it by name, ask for a specific element by its position in the array using the <code>nth</code> function.</p> <p>Then try some of the common functions that work on collections.</p> <pre><code>(def portfolio [ { :ticker \"CRM\" :lastTrade 233.12 :open 230.66}\n                 { :ticker \"AAPL\" :lastTrade 203.25 :open 204.50}\n                 { :ticker \"MSFT\" :lastTrade 29.12  :open 29.08 }\n                 { :ticker \"ORCL\" :lastTrade 21.90  :open 21.83 }])\n\nportfolio\n\n(nth portfolio 0)\n\n(nth portfolio 3)\n\n(first portfolio)\n(rest portfolio)\n(last portfolio)\n</code></pre> <p>First and next are termed as sequence functions in Clojure, unlike other lisps, you can use first and next on other data structures too</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 3a939f03e8df355150137c7b9d2f0fc86b6da5bd..b077cb494e42aadee576dcd804e3b0a740400ac4 100644
GIT binary patch
delta 15
Wcmca9aZ`d#zMF$1qiiEvFb@DJR0Nj*

delta 15
Wcmca9aZ`d#zMF$1pmZZ!Fb@DIzXW~&