Error formatting macro: pagetree: java.lang.NullPointerException

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Problem

Writing programs that target Clojure and ClojureScript involves a lot of copy and pasting. The usual approach is to copy the whole code of one implementation to a source file of the other implementation and to modify the platform dependent forms until they work on the other platform. Depending on the kind of program the platform specific code is often a fraction of the code that works on both platforms. A change to platform independent code requires a modification of two source files that have to be kept in sync. To solve this problem branching by target platform on a form level would help a lot.

See also ticket CLJS-27.

Current Solutions

There are several Clojure implementations (Clojure, ClojureScript, ClojureCLR). The problem we wish to solve is how to write a single source file that runs on more than one of these platform implementations, retaining all of the common code and factoring out only the platform-specific bits.

Known use cases for platform-specific functionality:

  • Platform-specific require/import (the most common case)
  • Exception handling (catch "all" is platform-specific - see http://dev.clojure.org/jira/browse/CLJ-1293 about this specific case)
  • Platform-specific calls for strings, dates, random numbers, uris, reflection warnings (hosty things)
  • Protocol implementations have leading dash in cljs so name is different
  • Extending protocol to implementation-specific classes (clojure.lang.IPersistentVector)
  • Math - casting or other math stuff specific to ClojureScript

There are other potential uses for conditionally including code based on factors other than platform (host architecture or presence of some external capability).

Current Solutions

Copy / paste

One approach is to maintain two versions of the same file that are largely the same but modify the platform-specific parts in each copy. This obviously works but is gross.

cljx

cljx is an implementation of feature expressions that:

  • rewrites .cljxfiles containing feature expression-annotated code into into external files based on well-known tags
    • The most common use is to use clj and cljs tags and write .clj and .cljs files for consumption by other tools/compilers/etc
  • optionally applies the same transformation interactively via installation of a REPL extension

...

  • It does not address portability of macros at all; it is strictly a source-to-source transformation.  Macros continue to be written in Clojure, and must be rewritten or implemented conditionally on the contents of &env.
  • It does not provide any runtime customization of the "features" you can use; these are set either within build configuration (via cljx' Leiningen integration), or via the configuration of the cljx REPL extension.  The latter technically is available for modification, but is not in practical use.
  • The set of provided "features" is limited to one for Clojure (#+clj) and one for ClojureScript (#+cljs).  Further discrimination based on target runtime (e.g. rhino vs. node vs. v8 vs. CLR) would be trivial, but has not been implemented to date. 

cljx expressions are typically applied:

  • Inside ns macro
  • Top-level forms
  • Occasionally internal forms where it's concise
    • (.getTime #+clj (java.util.Date.) #+cljs (js/Date.))
lein-cljsbuild "crossovers"

lein-cljsbuild provides a (deprecated, to be removed) feature called "crossovers" that provides a very limited preprocessing of certain files during the cljsbuild build process; a special comment string is removed, allowing one to work around the -macros declarations required in ClojureScript ns forms.  Crossover files must otherwise be fully portable.  Language/runtime-specific code must be maintained in separate files.  However, (my) experience shows that this can quickly lead to the situation where one has to think a lot about in which file to put a specific function, in order to go though the whole preprocessing machinery. Functions are split into namespaces because of conditional compilation, and not because they belong to the same part or module of the program.

Current uses of cljx

A survey of some existing cljx-using projects shows reasons for use:

  • Platform-specific require/import (easily the most common case)
  • Exception handling (catch "all" is platform-specific - see http://dev.clojure.org/jira/browse/CLJ-1293 for a ticket about this)
  • Platform-specific calls for strings, dates, random numbers, uris, reflection warnings
  • Protocol implementations have leading dash in cljs
  • Extending protocol to different class
  • Math - need casting in ClojureScript

And these are applied mostly:

  • Inside ns macro
  • Top-level forms
  • Occasionally internal forms in a conditional
    • (.getTime #+clj (java.util.Date.) #+cljs (js/Date.))

Potential Solution

Proposed Solution: feature expressions

A solution to this problem that is used by Common Lisp implementations are feature expressions. Each platform has a variable called *features* that contains keywords that indicate the supported features of the platform the code is running under. The branching on a platform or a platform specific feature is done via the reader macros #+ and #- followed by a feature condition. The feature condition is either a symbol or a form that combines symbols with the or, and or not operators. The feature condition is evaluated by looking up the symbols in the *features* variable. If the feature condition evaluates to true the next form will be passed through the reader and evaluated, otherwise it will be discarded.

...