Clojure In Small Pieces Rich Hickey Juozas Baliuka Eric Bruneton Chas Emerick Tom Faulhaber Stephen C. Gilardi Daniel Solano Gmez Christophe Grand Stuart Halloway Mike Hinchey Shawn Hoover Chris Houser Rajendra Inamdar Eugene Kuleshov Robert Lachlan J. McConnell Chris Nokleberg Allen Rohner Michel Salim Jason Sankey Stuart Sierra Frantisek Sodomka Vishal Vishnoi Jean Niklas L ́ orange Kyle Kingsbury Kai Wu Timothy Daly (Editor) Based on Version 1.3.0-alpha4 November 14, 2013 Contents Preface: Why Literate Programming i Steps to build Clojure . . . . . . . . . . . . . . . . . . . . . . . . . i Steps to change Clojure . . . . . . . . . . . . . . . . . . . . . . . . i Why Bother? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii 1 From The Ground Up (Kyle Kingsbury) 1 1.1 Clojure from the ground up . . . . . . . . . . . . . . . . . . . 1 1.1.1 Getting set up . . . . . . . . . . . . . . . . . . . . . . 1 1.1.2 The structure of programs . . . . . . . . . . . . . . . . 2 1.1.3 Review . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2 Clojure from the ground up: basic types . . . . . . . . . . . . 6 1.2.1 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.2 Integers . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.2.3 Fractional numbers . . . . . . . . . . . . . . . . . . . . 9 1.2.4 Mathematical operations . . . . . . . . . . . . . . . . 9 1.2.5 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.2.6 Booleans and logic . . . . . . . . . . . . . . . . . . . . 13 1.2.7 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.2.8 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.2.9 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.2.10 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.2.11 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.2.12 Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.2.13 Putting it all together . . . . . . . . . . . . . . . . . . 20 2 From ideas to implementation 23 2.1 Starting from Java . . . . . . . . . . . . . . . . . . . . . . . . 23 2.2 Extends and Implements . . . . . . . . . . . . . . . . . . . . . 23 2.3 Understanding Persistent Vectors (Jean Lorange) . . . . . . . 23 2.3.1 Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.3.2 Popping . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.3.3 O(1) != O(log n) . . . . . . . . . . . . . . . . . . . . . 31 2.3.4 Persistence . . . . . . . . . . . . . . . . . . . . . . . . 32 2.4 Red Black Trees . . . . . . . . . . . . . . . . . . . . . . . . . 39 i ii CONTENTS 2.4.1 Persistence . . . . . . . . . . . . . . . . . . . . . . . . 39 2.4.2 Persistent Red Black Trees . . . . . . . . . . . . . . . 39 2.4.3 Node Structure . . . . . . . . . . . . . . . . . . . . . . 40 2.4.4 The Black Node implementation . . . . . . . . . . . . 42 2.4.5 Constructing a Black Node . . . . . . . . . . . . . . . 45 2.4.6 The Red Node implementation . . . . . . . . . . . . . 46 2.4.7 Constructing a Red Node . . . . . . . . . . . . . . . . 49 2.4.8 Okasaki’s balance cases . . . . . . . . . . . . . . . . . 50 2.4.9 Deleting a Node . . . . . . . . . . . . . . . . . . . . . 52 2.4.10 Clojure’s balance cases . . . . . . . . . . . . . . . . . . 53 2.4.11 Replacing a Node . . . . . . . . . . . . . . . . . . . . . 55 2.5 Immutable Data Structures . . . . . . . . . . . . . . . . . . . 55 2.6 Bit-Partitioned Hash Tries . . . . . . . . . . . . . . . . . . . . 55 2.6.1 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 2.6.2 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 59 2.6.3 Hashmaps . . . . . . . . . . . . . . . . . . . . . . . . . 59 2.6.4 Seqs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 2.7 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 2.8 Java Interoperability . . . . . . . . . . . . . . . . . . . . . . . 62 2.8.1 Language primitives . . . . . . . . . . . . . . . . . . . 62 2.8.2 Clojure calling Java . . . . . . . . . . . . . . . . . . . 64 2.9 Recursion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 2.10 Argument Deconstruction . . . . . . . . . . . . . . . . . . . . 65 2.11 The Read-Eval-Print Loop . . . . . . . . . . . . . . . . . . . . 65 2.12 Special Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 2.13 Reader Macros . . . . . . . . . . . . . . . . . . . . . . . . . . 65 2.14 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 2.15 Dynamic Comopilation . . . . . . . . . . . . . . . . . . . . . . 66 2.16 Ahead-Of-Time Comopilation . . . . . . . . . . . . . . . . . . 66 2.17 Lazy Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 66 2.18 Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 2.19 Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 2.20 Identity and State . . . . . . . . . . . . . . . . . . . . . . . . 66 2.21 Software Transactional Memory . . . . . . . . . . . . . . . . . 67 2.22 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 2.23 The Lisp Reader . . . . . . . . . . . . . . . . . . . . . . . . . 69 2.23.1 Reader Syntax Macros . . . . . . . . . . . . . . . . . . 71 2.23.2 The String reader macro . . . . . . . . . . . . . . . . . 72 2.23.3 The Comment reader macro . . . . . . . . . . . . . . . 74 2.23.4 The Wrapping reader macro . . . . . . . . . . . . . . . 74 2.23.5 The Meta reader macro . . . . . . . . . . . . . . . . . 75 2.23.6 The SyntaxQuote reader macro . . . . . . . . . . . . . 76 2.23.7 The Unquote reader macro . . . . . . . . . . . . . . . 79 2.23.8 The List reader macro . . . . . . . . . . . . . . . . . . 80 2.23.9 The Unmatched Delimiter reader macro . . . . . . . . 80 2.23.10 The Vector reader macro . . . . . . . . . . . . . . . . 80 CONTENTS iii 2.23.11 The Map reader macro . . . . . . . . . . . . . . . . . . 81 2.23.12 The Character reader macro . . . . . . . . . . . . . . 81 2.23.13 The Arg reader macro . . . . . . . . . . . . . . . . . . 82 2.24 Reader Dispatch Macros . . . . . . . . . . . . . . . . . . . . . 83 2.24.1 The Var reader macro . . . . . . . . . . . . . . . . . . 84 2.24.2 The Regular Expression reader macro . . . . . . . . . 85 2.24.3 The Function reader macro . . . . . . . . . . . . . . . 86 2.24.4 The Set reader macro . . . . . . . . . . . . . . . . . . 87 2.24.5 The Eval reader macro . . . . . . . . . . . . . . . . . . 87 2.24.6 The Unreadable reader macro . . . . . . . . . . . . . . 89 2.24.7 The Discard reader macro . . . . . . . . . . . . . . . . 89 2.25 Vars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 2.26 Transients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 2.27 Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 2.28 Refs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 2.29 Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 2.30 Promise and Deliver . . . . . . . . . . . . . . . . . . . . . . . 94 2.31 Futures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 2.32 MultiMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 2.33 Deftype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 2.34 Defrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 2.35 Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 2.36 Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 2.37 Genclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 2.37.1 Overriding protected methods . . . . . . . . . . . . . . 102 2.38 Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 2.39 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 2.40 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 2.41 Generating Java Classes . . . . . . . . . . . . . . . . . . . . . 105 2.42 Type Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 2.43 Native Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . 105 3 Writing Idiomatic Clojure 107 4 The Ants Demo (Kai Wu) 109 4.1 The Simulation World . . . . . . . . . . . . . . . . . . . . . . 109 4.1.1 Initial setup of constants/magic-numbers . . . . . . . 109 4.1.2 The board: ready to mutate via transactions . . . . . 110 4.1.3 Ants as agents - doing asynchronous uncoordinated changes 112 4.1.4 Setting up the home, and ants . . . . . . . . . . . . . 113 4.1.5 Orientation and moving around the world . . . . . . . 115 4.1.6 Ant-agent behavior functions . . . . . . . . . . . . . . 116 4.1.7 World behavior: pheromone evaporation . . . . . . . . 124 4.2 The UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 4.2.1 Using the Java AWT . . . . . . . . . . . . . . . . . . . 125 4.2.2 Functions to render the board and the ants . . . . . . 126 iv CONTENTS 4.2.3 Setting the scene, then updating it continually . . . . 128 4.3 Running the Program . . . . . . . . . . . . . . . . . . . . . . 130 4.3.1 Running the simulator . . . . . . . . . . . . . . . . . . 130 5 Parallel Processing 133 5.1 Natural Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . 133 5.2 Steele’s parallel ideas . . . . . . . . . . . . . . . . . . . . . . . 133 5.3 Sequential mapreduce . . . . . . . . . . . . . . . . . . . . . . 137 5.3.1 Parallel mapreduce . . . . . . . . . . . . . . . . . . . . 139 5.4 MPI Message Passing . . . . . . . . . . . . . . . . . . . . . . 141 5.4.1 The N-colony Ant Demo . . . . . . . . . . . . . . . . . 141 5.5 MapReduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 6 The ant build sequence 143 6.1 ant.build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 6.2 The Execution . . . . . . . . . . . . . . . . . . . . . . . . . . 149 7 jvm/clojure/asm/ 163 7.1 AnnotationVisitor.java . . . . . . . . . . . . . . . . . . . . . . 163 7.2 AnnotationWriter.java . . . . . . . . . . . . . . . . . . . . . . 165 7.3 Attribute.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 7.4 ByteVector.java . . . . . . . . . . . . . . . . . . . . . . . . . . 176 7.5 ClassAdapter.java . . . . . . . . . . . . . . . . . . . . . . . . 183 7.6 ClassReader.java . . . . . . . . . . . . . . . . . . . . . . . . . 185 7.7 ClassVisitor.java . . . . . . . . . . . . . . . . . . . . . . . . . 229 7.8 ClassWriter.java . . . . . . . . . . . . . . . . . . . . . . . . . 233 7.9 Edge.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 7.10 FieldVisitor.java . . . . . . . . . . . . . . . . . . . . . . . . . 263 7.11 FieldWriter.java . . . . . . . . . . . . . . . . . . . . . . . . . . 264 7.12 Frame.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 7.13 Handler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 7.14 Item.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 7.15 Label.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 7.16 MethodAdapter.java . . . . . . . . . . . . . . . . . . . . . . . 314 7.17 MethodVisitor.java . . . . . . . . . . . . . . . . . . . . . . . . 317 7.18 MethodWriter.java . . . . . . . . . . . . . . . . . . . . . . . . 326 7.19 Opcodes.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 7.20 Type.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 8 jvm/clojure/asm/commons 413 8.1 AdviceAdapter.java . . . . . . . . . . . . . . . . . . . . . . . . 413 8.2 AnalyzerAdapter.java . . . . . . . . . . . . . . . . . . . . . . 426 8.3 CodeSizeEvaluator.java . . . . . . . . . . . . . . . . . . . . . 445 8.4 EmptyVisitor.java . . . . . . . . . . . . . . . . . . . . . . . . 449 8.5 GeneratorAdapter.java . . . . . . . . . . . . . . . . . . . . . . 453 8.6 LocalVariablesSorter.java . . . . . . . . . . . . . . . . . . . . 484 CONTENTS v 8.7 Method.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 8.8 SerialVersionUIDAdder.java . . . . . . . . . . . . . . . . . . . 496 8.9 StaticInitMerger.java . . . . . . . . . . . . . . . . . . . . . . . 506 8.10 TableSwitchGenerator.java . . . . . . . . . . . . . . . . . . . 508 9 jvm/clojure/lang/ 509 9.1 AFn.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 9.2 AFunction.java . . . . . . . . . . . . . . . . . . . . . . . . . . 519 9.3 Agent.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 9.4 AMapEntry.java . . . . . . . . . . . . . . . . . . . . . . . . . 527 9.5 APersistentMap.java . . . . . . . . . . . . . . . . . . . . . . . 530 9.6 APersistentSet.java . . . . . . . . . . . . . . . . . . . . . . . . 538 9.7 APersistentVector.java . . . . . . . . . . . . . . . . . . . . . . 541 9.8 AReference.java . . . . . . . . . . . . . . . . . . . . . . . . . . 552 9.9 ARef.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 9.10 ArityException.java . . . . . . . . . . . . . . . . . . . . . . . 556 9.11 ArrayChunk.java . . . . . . . . . . . . . . . . . . . . . . . . . 556 9.12 ArraySeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 9.13 ASeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 9.14 Associative.java . . . . . . . . . . . . . . . . . . . . . . . . . . 576 9.15 Atom.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 9.16 ATransientMap.java . . . . . . . . . . . . . . . . . . . . . . . 579 9.17 ATransientSet.java . . . . . . . . . . . . . . . . . . . . . . . . 581 9.18 BigInt.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 9.19 Binding.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 9.20 Box.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 9.21 ChunkBuffer.java . . . . . . . . . . . . . . . . . . . . . . . . . 586 9.22 ChunkedCons.java . . . . . . . . . . . . . . . . . . . . . . . . 586 9.23 Compile.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 9.24 Compiler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 9.25 Cons.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 9.26 Counted.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 9.27 Delay.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 9.28 DynamicClassLoader.java . . . . . . . . . . . . . . . . . . . . 769 9.29 EnumerationSeq.java . . . . . . . . . . . . . . . . . . . . . . . 770 9.30 Fn.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 9.31 IChunk.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 9.32 IChunkedSeq.java . . . . . . . . . . . . . . . . . . . . . . . . . 773 9.33 IDeref.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 9.34 IEditableCollection.java . . . . . . . . . . . . . . . . . . . . . 774 9.35 IFn.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774 9.36 IKeywordLookup.java . . . . . . . . . . . . . . . . . . . . . . 796 9.37 ILookup.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 9.38 ILookupSite.java . . . . . . . . . . . . . . . . . . . . . . . . . 797 9.39 ILookupThunk.java . . . . . . . . . . . . . . . . . . . . . . . . 798 9.40 IMapEntry.java . . . . . . . . . . . . . . . . . . . . . . . . . . 798 vi CONTENTS 9.41 IMeta.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 9.42 Indexed.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 9.43 IndexedSeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . 799 9.44 IObj.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 9.45 IPersistentCollection.java . . . . . . . . . . . . . . . . . . . . 800 9.46 IPersistentList.java . . . . . . . . . . . . . . . . . . . . . . . . 801 9.47 IPersistentMap.java . . . . . . . . . . . . . . . . . . . . . . . 801 9.48 IPersistentSet.java . . . . . . . . . . . . . . . . . . . . . . . . 802 9.49 IPersistentStack.java . . . . . . . . . . . . . . . . . . . . . . . 802 9.50 IPersistentVector.java . . . . . . . . . . . . . . . . . . . . . . 802 9.51 IPromiseImpl.java . . . . . . . . . . . . . . . . . . . . . . . . 803 9.52 IProxy.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 9.53 IReduce.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 804 9.54 IReference.java . . . . . . . . . . . . . . . . . . . . . . . . . . 804 9.55 IRef.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805 9.56 ISeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805 9.57 IteratorSeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . 806 9.58 ITransientAssociative.java . . . . . . . . . . . . . . . . . . . . 807 9.59 ITransientCollection.java . . . . . . . . . . . . . . . . . . . . . 808 9.60 ITransientMap.java . . . . . . . . . . . . . . . . . . . . . . . . 808 9.61 ITransientSet.java . . . . . . . . . . . . . . . . . . . . . . . . 809 9.62 ITransientVector.java . . . . . . . . . . . . . . . . . . . . . . . 809 9.63 Keyword.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 810 9.64 KeywordLookupSite.java . . . . . . . . . . . . . . . . . . . . . 816 9.65 LazilyPersistentVector.java . . . . . . . . . . . . . . . . . . . 817 9.66 LazySeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 818 9.67 LineNumberingPushbackReader.java . . . . . . . . . . . . . . 823 9.68 LispReader.java . . . . . . . . . . . . . . . . . . . . . . . . . . 825 9.69 LockingTransaction.java . . . . . . . . . . . . . . . . . . . . . 836 9.70 MapEntry.java . . . . . . . . . . . . . . . . . . . . . . . . . . 850 9.71 MapEquivalence.java . . . . . . . . . . . . . . . . . . . . . . . 850 9.72 MethodImplCache.java . . . . . . . . . . . . . . . . . . . . . . 851 9.73 MultiFn.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 852 9.74 Named.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861 9.75 Namespace.java . . . . . . . . . . . . . . . . . . . . . . . . . . 861 9.76 Numbers.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 9.77 Obj.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947 9.78 PersistentArrayMap.java . . . . . . . . . . . . . . . . . . . . . 948 9.79 PersistentHashMap.java . . . . . . . . . . . . . . . . . . . . . 955 9.80 PersistentHashSet.java . . . . . . . . . . . . . . . . . . . . . . 980 9.81 PersistentList.java . . . . . . . . . . . . . . . . . . . . . . . . 982 9.82 PersistentQueue.java . . . . . . . . . . . . . . . . . . . . . . . 989 9.83 PersistentStructMap.java . . . . . . . . . . . . . . . . . . . . 995 9.84 PersistentTreeMap.java . . . . . . . . . . . . . . . . . . . . . 1000 9.85 PersistentTreeSet.java . . . . . . . . . . . . . . . . . . . . . . 1012 9.86 PersistentVector.java . . . . . . . . . . . . . . . . . . . . . . . 1014 CONTENTS vii 9.87 ProxyHandler.java . . . . . . . . . . . . . . . . . . . . . . . . 1030 9.88 Range.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031 9.89 Ratio.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 9.90 Ref.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034 9.91 Reflector.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044 9.92 Repl.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054 9.93 RestFn.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055 9.94 Reversible.java . . . . . . . . . . . . . . . . . . . . . . . . . . 1094 9.95 RT.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094 9.96 Script.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138 9.97 SeqEnumeration.java . . . . . . . . . . . . . . . . . . . . . . . 1138 9.98 SeqIterator.java . . . . . . . . . . . . . . . . . . . . . . . . . . 1139 9.99 Seqable.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140 9.100Sequential.java . . . . . . . . . . . . . . . . . . . . . . . . . . 1140 9.101Settable.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140 9.102Sorted.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141 9.103StringSeq.java . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141 9.104Symbol.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143 9.105TransactionalHashMap.java . . . . . . . . . . . . . . . . . . . 1145 9.106Util.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149 9.107Var.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152 9.108XMLHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . 1164 10 jvm/clojure 1167 10.1 main.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167 11 clj/clojure/ 1169 11.1 core.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169 11.2 protocols.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296 11.3 core ̇deftype.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1298 11.4 core ̇print.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315 11.5 core ̇proxy.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323 11.6 data.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332 11.7 genclass.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334 11.8 gvec.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351 11.9 inspector.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 11.10browse.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365 11.11browse ̇ui.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366 11.12io.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367 11.13javadoc.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376 11.14shell.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378 11.15main.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381 11.16parallel.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389 11.17cl ̇format.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394 11.18column ̇writer.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1436 11.19dispatch.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1438 viii CONTENTS 11.20pprint ̇base.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448 11.21pretty ̇writer.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1456 11.22print ̇table.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467 11.23utilities.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467 11.24pprint.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470 11.24.1 java.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471 11.25reflect.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1476 11.26repl.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 11.27set.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1485 11.28stacktrace.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1489 11.29string.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490 11.30template.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496 11.31junit.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497 11.32tap.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501 11.33test.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1503 11.34version.properties . . . . . . . . . . . . . . . . . . . . . . . . . 1519 11.35walk.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1519 11.36xml.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1522 11.37zip.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524 11.38pom-template.xml . . . . . . . . . . . . . . . . . . . . . . . . 1531 12 test/clojure 1533 12.1 test/test ̇clojure.clj . . . . . . . . . . . . . . . . . . . . . . . . 1533 12.2 test/test ̇helper.clj . . . . . . . . . . . . . . . . . . . . . . . . 1535 12.3 test/agents.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537 12.4 test/annotations.clj . . . . . . . . . . . . . . . . . . . . . . . . 1541 12.5 test/atoms.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1541 12.6 test/clojure ̇set.clj . . . . . . . . . . . . . . . . . . . . . . . . 1542 12.7 test/clojure ̇xml.clj . . . . . . . . . . . . . . . . . . . . . . . . 1546 12.8 test/clojure ̇zip.clj . . . . . . . . . . . . . . . . . . . . . . . . 1547 12.9 test/compilation.clj . . . . . . . . . . . . . . . . . . . . . . . . 1548 12.10test/control.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1550 12.11test/data.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556 12.12test/data ̇structures.clj . . . . . . . . . . . . . . . . . . . . . . 1557 12.13test/def.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574 12.14test/errors.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575 12.15test/evaluation.clj . . . . . . . . . . . . . . . . . . . . . . . . 1576 12.16test/for.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1580 12.17test/genclass.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1583 12.18test/java ̇interop.clj . . . . . . . . . . . . . . . . . . . . . . . . 1585 12.19test/keywords.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1594 12.20test/logic.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1594 12.21test/macros.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1599 12.22test/main.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599 12.23test/metadata.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1600 12.24test/multimethods.clj . . . . . . . . . . . . . . . . . . . . . . 1602 CONTENTS ix 12.25test/ns ̇libs.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605 12.26test/numbers.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1607 12.27test/other ̇functions.clj . . . . . . . . . . . . . . . . . . . . . . 1618 12.28test/parallel.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1620 12.29test/pprint.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621 12.30test/predicates.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1621 12.31test/printer.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1624 12.32test/protocols.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1626 12.33test/reader.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633 12.34test/reflect.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640 12.35test/refs.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640 12.36test/repl.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641 12.37test/rt.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642 12.38test/sequences.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1644 12.39test/serialization.clj . . . . . . . . . . . . . . . . . . . . . . . 1668 12.40test/special.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1671 12.41test/string.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672 12.42test/test.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1674 12.43test/test ̇fixtures.clj . . . . . . . . . . . . . . . . . . . . . . . . 1677 12.44test/transients.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1678 12.45test/vars.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 12.46test/vectors.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1680 12.47test/java ̇5.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 12.48test/java ̇6 ̇and ̇later.clj . . . . . . . . . . . . . . . . . . . . . . 1688 12.49test/examples.clj . . . . . . . . . . . . . . . . . . . . . . . . . 1690 12.50test/io.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691 12.51test/javadoc.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1696 12.52test/shell.clj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696 12.53test/test ̇cl ̇format.clj . . . . . . . . . . . . . . . . . . . . . . . 1697 12.54test1/test ̇helper.clj . . . . . . . . . . . . . . . . . . . . . . . . 1714 12.55test/test ̇pretty.clj . . . . . . . . . . . . . . . . . . . . . . . . 1715 12.56test1/examples.clj . . . . . . . . . . . . . . . . . . . . . . . . 1721 12.57test/more ̇examples.clj . . . . . . . . . . . . . . . . . . . . . . 1722 12.58test/example.clj . . . . . . . . . . . . . . . . . . . . . . . . . . 1722 A External Java References 1723 B Copyright and Licenses 1725 C Building Clojure from this document 1733 C.1 The basic idea . . . . . . . . . . . . . . . . . . . . . . . . . . 1733 C.2 The tangle function in C . . . . . . . . . . . . . . . . . . . . . 1733 C.3 Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737 C.4 The tangle function in Clojure . . . . . . . . . . . . . . . . . 1744 C.4.1 Author and License . . . . . . . . . . . . . . . . . . . 1744 C.4.2 Abstract and Use Cases . . . . . . . . . . . . . . . . . 1744 x CONTENTS C.4.3 The Latex Support Code . . . . . . . . . . . . . . . . 1746 C.4.4 Imports . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 C.4.5 The Tangle Command . . . . . . . . . . . . . . . . . . 1748 C.4.6 The say function . . . . . . . . . . . . . . . . . . . . . 1748 C.4.7 The read-file function . . . . . . . . . . . . . . . . . . 1748 C.4.8 The ischunk function . . . . . . . . . . . . . . . . . . . 1749 C.4.9 The haschunks function . . . . . . . . . . . . . . . . . 1750 C.4.10 The expand function . . . . . . . . . . . . . . . . . . . 1751 C.4.11 The tangle function . . . . . . . . . . . . . . . . . . . 1751 Bibliography 1753 Index 1755 CONTENTS xi Foreword Rich Hickey invented Clojure. This is a fork of the project to experiment with literate programming as a development and documentation technology. Every effort is made to give credit for any and all contributions. Clojure is a break with the past traditions of Lisp. This literate fork is a break with the past traditions of code development. As such it is intended as an experiment, not a replacement or competition with the official version of Clojure. Most programmers are still locked into the idea of making a program out of a large pile of tiny files containing pieces of programs. They do not realize that this organization was forced by the fact that machines like the PDP 11 only had 8k of memory and a limit of 4k buffers in the editor. Thus there was a lot of machinery built up, such as overlay linkers, to try to reconstruct the whole program. The time has come to move into a more rational means of creating and main- taining programs. Knuth suggested we write programs like we write literature, with the idea that we are trying to communicate the ideas to other people. The fact that the machine can also run the programs is a useful side-effect but not important. Very few people have seen a literate program so this is intended as a complete working example, published in book form. The intent is that you can sit and read this book like any other novel. At the end of it you will be familiar with the ideas and how those ideas are actually expressed in the code. If programmers can read it and understand it then they can maintain and modify it. The ideas will have been communicated. The code will be changed to match changes in the idea. We will all benefit. I’ve tried to make it as simple as possible. Try it once, you might like it. Tim Daly December 28, 2010 ((iHy)) CONTENTS i Preface: Why Literate Programming This is a literate program, inspired by Donald Knuth [Knu84]. It is intended to be read like a novel from cover to cover. The ideas are expressed clearly but they are grounded in the actual source code. The code in this documment is the executable source. The appendix gives the procedure for building a running system from the enclosed sources. Steps to build Clojure Step 1 Basically you need the C program [1733] tangle.c which you can clip using a text editor and save it as tangle.c. Step 2 Compile tangle.c to create a function called tangle. gcc -o tangle tangle.c Step 3 Run tangle to extract the [1737] Makefile from this document. tangle clojure.pamphlet Makefile >Makefile Step 4 make This will • create a new subdirectory called “tpd” containing all of the source code • test Clojure • create a running copy of Clojure • create the pdf • start a Clojure REPL Steps to change Clojure If you make changes to this document and want the new changes just type: rm -rf tpd tangle clojure.pamphlet Makefile >Makefile make or you can combine them into one line: rm -rf tpd && tangle clojure.pamphlet Makefile >Makefile && make ii CONTENTS This will destroy the old source, extract the Makefile, and rebuild the system. On a fast processor this takes about a minute. Resist the urge to edit the files in the tpd directory. They are only there for the compiler. Edit this file directly. You can change where Clojure is built. In the [1737] Makefile there is a line which defines the root of the directory build. You can change this or override it on the command line to build Clojure elsewhere. WHERE=tpd To build a second copy of Clojure, or to work in some other directory, just type make WHERE=newplace Why Bother? Why bother with such a difficult method of programming? Because worthwhile programs should “live”. Programs “live” because people maintain them. Maintaining and modifying code correctly requires that you understand why the program is written as it is, what the key ideas that make the program work, and why certain, not very obvious, pieces of code exist. Programmers almost never write this information down anywhere. Great ideas are invented, the code is written, a man page of documentation is created, and the job is done. Well, almost. What does is mean for a program to “live”? How does a program survive once the original developers leave the project? There are many sources of information but almost no source of knowledge. New programmers don’t know what the “elders” know. In order to “live” and continue to grow there has to be a way to transmit this knowledge. Literate programming is Knuth’s proposed idea for moving from the world of ideas to the world of information. This is not simply another documentation format. This is meant to be Literature The ideas are presented, the impli- cations are explored, the tradeoffs are discussed, and the code is “motivated”, like characters in a novel. You are encouraged to write or rewrite sections of this document to improve the communication with the readers. “But I have to learn latex!”. Well, for this document you do. But L A TEXis just more than a document markup language like HTML and it is no harder to learn. It gives you the added advantage that you have a real language for publishing real documents. Most books are typeset with this technology and a lot of conferences and Journals require it. If you can learn Clojure, you can learn L A TEX. If you’re a programmer you will always need to continue to learn, at least until you retire into management. CONTENTS iii Having used literate programming for years I have collected some key quotes that might stimulate your interest. I believe that the time is ripe for significantly better documentation of pro- grams, and that we can best achieve this by considering programs to be works of literature. Hence, my title “Literate Programming”. Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate on explaining to human beings what we want a computer to do. –Donald Knuth “Literate Programming (1984)” Step away from the machine. Literate programming has nothing to do with tools or style. It has very little to do with programming. One of the hard transitions to literate programming is “literate thinking”. –Timothy Daly in Lambda the Ultimate (2010) The effect of this simple shift of emphasis can be so profound as to change one’s whole approach to programming. Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the com- puter to behave in a particular way. It is the difference between performing and exposing a magic trick. –Ross Williams, FunnelWeb Tutorial Manual Another thing I’ve been enjoying lately is literate programming. Amazingly it turns out to be faster to write a literate program than an ordinary program because debugging takes almost no time. –Bill Hart, SAGE Mailing list, May 3, 2010 The conversation is much more direct if the Design Concept per se, rather than derivative representatives or partial details, is the focus. –Fred Brooks, “The Design of Design” We are banning the old notion of literate programming that I used when developing TEX82 because documentation has proven to be too much of a pain. –Donald Knuth TUG 2010 iv CONTENTS Once upon a time I took great care to ensure that TEX82 would be truly archival so that results obtainable today would produce the same output 50 years from now but that was manifestly foolish. Let’s face it, who is going to care one whit for what I do today after even 5 years have elapsed, let alone 50. Life is too short to re-read anything anymore in the internet age. Nothing over 30 months old is trustworthy or interesting. –Donald Knuth TUG 2010 Chapter 1 From The Ground Up (Kyle Kingsbury) This is quoted from Kingbury. [King13] 1.1 Clojure from the ground up 1.1.1 Getting set up When you have a JDK, youll need Leiningen, the Clojure build tool. If youre on a Linux or OS X computer, these instructions should get you going right away. If youre on Windows, see the Leiningen page for an installer. If you get stuck, you might want to start with a primer on command line basics. mkdir -p ~/bin cd ~/bin wget https://raw.github.com/technomancy/leiningen/stable/bin/lein chmod a+x lein Leiningen automatically handles installing Clojure, finding libraries from the internet, and building and running your programs. Well create a new Leiningen project to play around in: cd lein new scratch This creates a new directory in your homedir, called scratch. If you see command not found instead, it means the directory /bin isnt registered with your terminal as a place to search for programs. To fix this, add the line 1 2 CHAPTER 1. FROM THE GROUND UP (KYLE KINGSBURY) export PATH="$PATH":~/bin to the file .bash ̇profile in your home directory, then run source ~/.bash_profile. Re-running lein new scratch should work. Lets enter that directory, and start using Clojure itself: cd scratch lein repl 1.1.2 The structure of programs boa$ lein repl which responds with nREPL server started on port 45413 REPL-y 0.2.0 Clojure 1.5.1 Docs: (doc function-name-here) (find-doc "part-of-name-here") Source: (source function-name-here) Javadoc: (javadoc java-object-or-class-here) Exit: Control+D or (exit) or (quit) user=> This is an interactive Clojure environment called a REPL, for Read, Execute, Print Loop. Its going to read a program we enter, run that program, and print the results. REPLs give you quick feedback, so theyre a great way to explore a program interactively, run tests, and prototype new ideas. Lets write a simple program. The simplest, in fact. Type nil, and hit enter. user=> nil nil nil is the most basic value in Clojure. It represents emptiness, nothing-doing, not-a-thing. The absence of information. user=> true true user=> false false 1.1. CLOJURE FROM THE GROUND UP 3 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. user=> 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: user=> "hi there!" "hi there!" nil, true, 0, and ”hi there!” are all different types of values; the nouns of pro- gramming. Ju