are there any documentation on clojure built-in java method?
for example, .toUpperCase from java.lang.String and .indexOf from clojure.lang.PersistantVector.
Is there anyway I can find useful java method without looking at the source code?
As others have pointed out, you can get the java.* and javax.* documentation online pretty easily as it is part of core Java.
For the clojure.*, your best reference is the source. Even so, I'd recommend not relying on it since this code should really be considered an implementation detail of Clojure. You have no guarantee that the functionality won't change in future versions of Clojure and break any code that depends on it.
How about the Java API? All of Java's classes and methods are listed there. That covers all of the "clojure built-in java methods".
On the other hand, Clojure's classes are documented in here, Clojure's API. You have to learn to distinguish between Clojure's classes and Java's classes. All packages starting with java.* or javax.* belong to Java and are documented in the first link. The packages starting with clojure.* are from Clojure, you'll find their documentation in the second link.
If the package for the class starts with java or javax then you can look it up in the Java documentation on Oracle's website.
For Clojure implementation classes (where the package name starts with clojure) you are probably stuck with looking at the source code. There is documentation for the intended API (the Clojure language) but not for the Java classes implementing it. You may be able to find some articles (like this one) depending on if what you're looking for is something a blogger has taken an interest in.
Related
Something is puzzling me after reading the this great answer to a related question:
There are two possibilities to share a function that I wrote in Clojure with Java developers
The first one is providing it in a JAR file so that they can call it as if I had written it in Java. Sounds great for Clojure advocacy.
The second one, the purportedly better way, requires those Java developers to use things like clojure.lang.IFn or clojure.lang.RT and invoking functions by passing their names as strings (!) instead of just calling them.
Why is the second approach "the better one"?
You are sorta setting up a false dichotomy here. Every approach involves creating a jar file: that is just how JVM programs are distributed. But there are 3 different ways for Java code to invoke Clojure code contained in a jar:
Use methods in clojure.lang.RT to initialize the runtime, load files, and then look up vars. This is the old, deprecated approach.
Use methods in clojure.java.api.Clojure to look up functions and invoke them. This is the newer version of (1), and hides some of the messy stuff you could accidentally get wrong.
Use gen-class in the Clojure library to define a more Java-friendly interface to the Clojure functions.
You can still do (3) - there's nothing wrong with it exactly. But gen-class is a pretty clunky tool, and except for the simplest examples like exposing a number of static methods, it's just not a lot of fun, and it's not easy to provide an API that "feels" like a Java API using Clojure.
But you know what's great at providing an API that feels like Java? Java! So what I recommend if you want to make a Clojure library easy to use in Java is to include some Java code in your Clojure library. That Java code, written by you, bridges the language gap. It accesses your Clojure code by mechanism (2) above, and presents a Java-friendly facade so the outside world doesn't have to know there's Clojure underneath.
amalloy/thrift-gen is an example of a library I wrote years ago following this approach. It would not be at all easy to write this in pure Clojure, just because traditional Java idioms are very foreign to Clojure, and it doesn't support them all very well. By writing my own Java shim instead, Java clients get a very comfortable interface to work with, and I can just write Clojure that feels like Clojure instead of a bunch of gen-class nonsense.
It looks like exposing clojure library api to Java code requires the use of AOT compilation (at least when the exposed api is OO). If I'm wrong about that, I am happy to be revised. In the past, there have been multiple issues with AOT, thusly relying on it may have seemed a bit reckless or unstable.
What is the current state in that?
Is it a safe practice?
Would you use that as a means to expose an OO api to java applications?
You can use AOT to produce bytecode that will pass muster as a Java library. But it's not terribly pleasant, for you or for the Java programmers, who will rightfully ask: Where is the JavaDoc? Why are you using Object instead of generics? And other similarly awkward questions.
Instead, my preferred approach is to not make the Clojure code Java-friendly at all. Expose it as ordinary Clojure vars, and that's it. Then, write some Java code yourself, in the same library, that consumes the Clojure-based API and repackages it in terms of whatever Java constructs you want.
For one example, see my thrift-gen library. Using it from Clojure, you get a function that takes a map as input and produces a sequence; using it from Java, you get a builder pattern for configuration instead of the map, and you get a List<? extends T> as output. No JavaDoc, because I felt the usage documentation in the readme was sufficient, but if I were serious about using this there is a real .java source file to easily add JavaDoc to.
My question is NOT about how to use ClojureScript to produce JavaScript code.
I am interested in ClojureScript because it implements Clojure \ {eval} within Clojure, and is able to compile it to another language. Thus, I'm interested in the possibility of having ClojureScript target other platforms.
Question: besides the source code, is the Design & Implementation of ClojureScript documented anywhere? I'd like a high level overview of how the various parts of the compiler work together:
* how are the
As far as the documentation for "Clojurescript pipeline and how you can hook into it" is concerned you can check out this blog entry.
Are there any implementations of Clojure being built for other virtual machines (such as .Net, Python, Ruby, Lua), or is it too closely tied to Java and the JVM? Does it make sense to build a Clojure for other platforms?
There are currently three implementations of Clojure that I know of:
ClojureCLR, an implementation of Clojure for the CLI,
ClojureScript, an implementation of (a subset of (a variant of)) Clojure for ECMAScript and
a Clojure implementation for the Java platform, confusingly also called Clojure.
In fact, the name Clojure was specifically chosen by Rich Hickey because it contained both the letters CLR as well as the letter J.
I've heard rumours of implementations for the Objective-C/Cocoa runtime, LLVM and the Rubinius VM, but I have no idea whether or not those actually exist.
" or is it too closely tied to Java and the JVM?
Does it make sense to build a Clojure for other platforms?"
One of the Clojure design philosophies is embrace the host platform. Clojure on the JVM embraces the JVM and gives direct access to classes, numbers etc. interop is both ways with out glue.
ClojureScript embraces JavaScript(ECMAScript) in exactly the same way, giving direct access to Objects, numbers, etc. the same for the .NET target.
It is tempting, but not always successful, to make 'cross platform' languages that run the exact same source code on multiple platforms. Thus far Clojure has avoided this temptation and strives to remain close to the host.
There exits at least a ClojureCLR project by Rich Hickey himself.
This project is a native implementation of Clojure on the Common Language Runtime (CLR),
the execution engine of Microsoft's .Net Framework.
ClojureCLR is programmed in C# (and Clojure itself) and makes use of Microsoft's
Dynamic Language Runtime (DLR).
I'm not sure that Python and Ruby ports make sense, those are languages with multiple virtual machines / implementations. If you want to have native interop between Clojure and Python or Ruby you could use Jython or JRuby and stay on the JVM.
What's the best way to embed Ruby as a scripting language in C++? Using ruby.h? SWIG? Something else? What I need is to expose some C++ objects to Ruby and have the Ruby interpreter evaluate scripts that access these objects. I don't care about extending Ruby or accessing it in C++.
I've found this article on embedding Ruby in C++, and while it's very useful, it's kinda old and I was wondering if there are any other resources on the subject (or open source implementations of similar engines).
Rice is looking very promising.
Ruby provides a very helpful README.EXT file. It has lots of information about how to extend Ruby, and convert between C & Ruby types.
There is also this excerpt from the pick axe book which pretty much covers the same thing.
In my case, when I added Ruby scripting to my application I decided against using swig, because my needs were very simple, and I didn't want to add yet another build dependency.
swig is probablly the way to go..... but ruby doesnt embed too well......
if you want a language that embeds nicely into C++, try lua
You might wish to check out tinyrb.
I've been working on Rarity (https://github.com/Plaristote/Rarity), which does two things:
Generates Ruby bindings from a YML description of your C++ API
Allows interaction with Ruby script in the most C++ fashion there is
I've solved a good deal of question (exception handling, garbage collection)...
I haven't seen anywhere else the code generation that Rarity uses to make your bindings come to life. I also haven't seen any other lib that allows such an easy conversion between C++ and Ruby types.
I think Rarity's worth the shot ! And I'd be glad to have some feedback as well :) !