GithubHelp home page GithubHelp logo

clojure-cookbook / clojure-cookbook Goto Github PK

View Code? Open in Web Editor NEW
2.6K 2.6K 435.0 11.13 MB

This is the home of O'Reilly's Clojure Cookbook - http://clojure-cookbook.com

Clojure 44.31% Shell 27.04% CSS 5.74% XSLT 22.91%

clojure-cookbook's Introduction

Clojure Cookbook

Clojure Cookbook marks Clojure's entry into O'Reilly's prestigious Cookbook Series. The book details a large number of recipes – pairs of problems and solutions – for common topics in Clojure.

Clojure Cookbook doesn't just teach you Clojure, it also shows you how to use the language and many of its common libraries. The most difficult part of mastering any language is knowing how to apply it, in an idiomatic way, to tasks that real software developers encounter every day. This is especially true of Clojure.

With code recipes that teach you how to use the language in a variety of domains, Clojure Cookbook goes beyond simply teaching Clojure syntax and semantics. It contains annotated example code with detailed analysis and explanation for hundreds of real programming tasks. You can read the book straight through to gain insights about Clojure, or use it as a reference to solve particular problems.

Exploring the Book

If you're an Emacs-wielding Clojurist, you will probably want to read this book in Emacs, too. Here is a function that "turns the page" from one recipe to the next (find and open the next recipe, close the buffer with the previous recipe).

(defun increment-clojure-cookbook ()
  "When reading the Clojure cookbook, find the next section, and
close the buffer. If the next section is a sub-directory or in
the next chapter, open Dired so you can find it manually."
  (interactive)
  (let* ((cur (buffer-name))
	 (split-cur (split-string cur "[-_]"))
	 (chap (car split-cur))
	 (rec (car (cdr split-cur)))
	 (rec-num (string-to-number rec))
	 (next-rec-num (1+ rec-num))
	 (next-rec-s (number-to-string next-rec-num))
	 (next-rec (if (< next-rec-num 10)
		       (concat "0" next-rec-s)
		     next-rec-s))
	 (target (file-name-completion (concat chap "-" next-rec) "")))
    (progn 
      (if (equal target nil)
	  (dired (file-name-directory (buffer-file-name)))
	(find-file target))
      (kill-buffer cur))))

If you wish, you can then bind the function to a key:

(define-key adoc-mode-map (kbd "M-+") 'increment-clojure-cookbook)

Of course, this binding assumes you're using adoc-mode for reading .asciidoc files. We suggest CIDER for evaluating code interactively. Adding the following hook to your config will enable cider-mode every time you enter an AsciiDoc file. Once active, you can start a REPL and evaluate code like you would do in any regular Clojure file.

(add-hook 'adoc-mode-hook 'cider-mode)

Contributing

As of Jan. 10, 2014 we are preparing the book for print. See CONTRIBUTING.md for more info.

Building the Book

You can build a PDF/MOBI/EPUB/HTML version of the book with the asciidoc command-line utility. (You must also have the source-highlight application installed and properly configured.)

Pre-requisites

You must have the asciidoc and source-highlight command-line utilities installed and configured before attempting to build the book.

To install and configure the tools on OS X or Linux, run the included bootstrap.sh script:

$ ./script/asciidoc/bootstrap.sh

Rendering

With installation and configuration complete, all that is left is to run the asciidoc command.

  • To render a single document:

    $ asciidoc -b html5 conventions.asciidoc
    # ... outputs conventions.html
  • To render the entire book:

    $ asciidoc -b html5 book.asciidoc
    # ... outputs book.html

NOTE: Rendered output is similar to the final book, but does not include O'Reilly style sheets.

Testing

To verify asciidoc files are without error/warning, run the following:

$ ./script/asciidoc/check.sh

The only output should be the file detail.

Fixing Asciidoc Warnings/Errors

The only acceptable warning is related to structure of the book sections. It's OK to ignore this one:

asciidoc: WARNING: conventions.asciidoc: line 1: section title out of sequence: expected level 1, got level 2

Please correct all others or ask for guidance if the error message is unclear. A common one is related to callouts like "<1>" at the end of a line of code.

asciidoc: WARNING: formatting-strings.asciidoc: line 57: no callouts refer to list item 1

To prevent this warning, the callout must be commented using the language appropriate comment character(s). This also keeps the code runnable in the REPL when pasted.

Clojure Example:

(defn foo [] "bar" ) <1>

requires a semicolon before the callout reference

(defn foo [] "bar" ) ; <1>

Console Example:

Username: <1>

should be

Username: #<1>

Who we are

We are Luke Vanderhart (@levand) and Ryan Neufeld (@rkneufeld), developers, authors, conference speakers and (at the moment), teachers. For this book-building adventure we will be your guides; we'll be collecting and editing your contributions, interfacing with the publisher (O'Reilly) and writing a solid chunk of the book ourselves.

License

Creative Commons License
This draft of Clojure Cookbook is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

Please see the contribution guide for how this works for accepting pull requests.

Also, please note that because this is a No Derivatives license, you may not use this repository as a basis for creating your own book based on this one. Technically speaking, this book is open source in the "free as in beer" sense, rather than "free as in speech."

clojure-cookbook's People

Contributors

0rca avatar adambard avatar alexrobbins avatar cjfrisz avatar cloojure avatar daemianmack avatar dz-cies avatar hickst avatar ianconsolata avatar ifesdjeen avatar indexpro avatar jcromartie avatar josephwilk avatar levand avatar levand2 avatar maravillas avatar miner avatar mmullis avatar mrwhelan avatar mwfogleman avatar nangia avatar nbessi avatar robert-stuttaford avatar siscia avatar stevenproctor avatar thebusby avatar theleoborges avatar tobiasbayer avatar yogthos avatar zclj avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

clojure-cookbook's Issues

CONTRIBUTING.md should include instructions on recipe dependencies

As per the discussion in #54 CONTRIBUTING.md should include instructions on how to introduce a library dependency to a recipe both in its own project.clj (this may necessitate fleshing out the sub-project story) as well as how to tastefully mention this possibly versioned dependency to the recipe text itself.

Add asciidoc toolchain help in README.md

Editing the raw asciidoc source is a frustrating way to preview one's own recipes. I managed to get asciidoc running and generating HTML copies of this book locally for editing purposes, but the following hints, perhaps added to the README, would be helpful:

  1. clojure syntax highlighting. This required a bunch of googling around but I was eventually able to get this to work.
  2. PDF generation. Some things[1] would be easier to check/preview/test if we could make our own PDFs. I still haven't gotten this to work with asciidoc/docbook.

I'm willing to help out on this one but could use help with (2).

[1] footnotes

Idea: Web scraping example with a few different libraries

My idea is to provide some trivial html and then scrape it the same way with at least Enlive and Laser.

The example would be as short and simple as possible, intended to show you how to load the html with each library and let you compare their syntax. I have to look up these semantics every time I switch between these libraries.

Idea: Local IO XML

I have started to put together read/write of XML for addition to the local io chapter. If that sounds like a good idea you can put this one to in-progress and I'll will keep working on it.

Problem: Specifying library versions??

A lot of problems can be practically solved by referring to third party libraries. The twitter api is an example of this.

We can specify versions within each recipe, but I wonder if we shouldn't just mention the library versions in the description and where people can grab the latest release.

Thoughts?

Chapter idea: Fun Problems

The current proposed chapters look pretty comprehensive. However, one Chapter that I find missing is "Fun Problems". These are problems that are just fun to solve. Example recipes in this chapter could be various kind of algorithmic problems or puzzles or other misc. stuff which are fun to solve. Like:

I could contribute many of such recipes for this chapter. e.g. Look at some of the problems I have solved in python at https://github.com/nangia/funproblems and in clojure at https://github.com/nangia/funwithclojure. While there is no detailed documentation that I have put in on github yet, I can write up detailed recipes for the book to explain how these can be solved.

Thanks and regards,

Sandeep
http://in.linkedin.com/in/sandeepnangia/

Idea: data validation

I was thinking of creating a recipe for a pattern I use to validate input by applying a vector of validation functions and reducing to a set of booleans. Not sure where that would belong in the structure of the book, though. Any Ideas? Speaking of ideas, I can't seem to add a label to this issue. Looks like I have to be an existing contributor?

Question: Can I post my work on my blog

Hi,

a little question, just to be sure and to don't mess around.

If I write recipe for you, then there are any problems if I publish my own recipes on my own blog ?
O'Reilly is fine with that ?

Idea: Manipulate lists of non-trivial data

For example, compare lists of time-slots. A time-slot being an arbitrary length of time defined by a point in time and a duration. The recipe could show how to find overlaps of time slots (say for a scheduling system) via intersections of the times in multiple lists. Another manipulation could be to find open time slots (as in a booking system).

The point being would be to show the utility of the union/difference/intersection/etc functions, but not just on plain/simple lists. The above example is complex enough to not be trivial.

Cross reference examples using file-seq with "Get files from a directory"

There are currently a few recipes in the Local I/O chapter that utilize file-seq with clojure.java.io/file to get a list of files from a directory. Any such recipes should include an AsciiDoc Internal Cross Reference from those recipes See Also section to the Get files from a directory recipe.

The reference will look something like this:

===== See Also

* <<sec_primitives_strings_re_find>> for testing a string for the
  presence of a pattern.

and the target recipe will look like this:

[[sec_primitives_strings_find_replace]]
==== Performing Find and Replace on Strings

Potential updates for the Local I/O file copying recipe

Here is a list of updates I'd like to make to the Copy a file recipe

  • Use AsciiDoc callouts for safe-copy example. (This may be a bit difficult for others until we get better instructions for rendering.)
  • Possibly include an example of using Reader/Writer with clojure.java.io/copy
  • Discuss possible implications of buffer size being what it is. What does this mean when using the function.
  • Make Fixup link to "Reading and writing files" on L70 a proper AsciiDoc link. ([[sec_....]] and <<sec_...>> pairs)

What about image ?

Should we include images if necessary ?

There are dimension that we need to stay in ?

Edit a bitmap image

Java (and by proxy, Clojure) is capable of low-level graphics manipulation. Including an example of this would be interesting.

Potential updates for the Local I/O file list recipe

Here is a list of updates I'd like to make to the Get files from a directory recipe

  • Threading macros in this recipe do not need parens wrapped around every single arg step.
  • There is a keyword and few other bits of "cody" outside of a code block that could be wrapped in +s
  • The file path splitting here is not actually platform agnostic, it'd be best to rely on something coming out of #76 to solve this.

Polyglot Clojure <-> Java projects

The main road for Clojure developers is to code in Clojure and to optionally depend on some external Java based libraries/ frameworks. Clojure with its built-in Java interoperability makes this very easy.

In an enterprise Java environment, where introduction of new technologies such as Clojure might face some resistance due to risk considerations, a possible solution is to pick one component, code it in Clojure, and keep the rest in well known Java land. A Java interface, implemented in Clojure, and used from Java, requires an elaborate build setup.

Idea: Extend native java types!

Extend Java native types. For example, we could add an isPalindrome? method to java.lang.String via extend-type:

user=> (defprotocol Palindrome
  #_=>   (isPalindrome? [this]))
Palindrome
user=> (extend-type String
  #_=>   Palindrome
  #_=>   (isPalindrome? [this] (let [base-string (-> this
  #_=>                                          (clojure.string/replace #"[,.! ]" "")
  #_=>                                          .toLowerCase)]
  #_=>                               (= base-string
  #_=>                                  (clojure.string/reverse base-string)))))
nil
user=> (def test-string "A man, a plan, a canal. Panama!")
#'user/test-string
user=> (class test-string)
java.lang.String
user=> (isPalindrome? test-string)
true

Idea: Pedestal Recipe

I'd be happy to give this a shot. Do you think it's stable enough to get its own recipe?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.