devtools.munging — binaryage/devtools 1.0.0

cljs

This namespace implements various heuristics to map Javascript names back to corresponding ClojureScript names. The functionality here heavily depends on observed ClojureScript compiler and runtime behaviour (fragile!). Answers given by functions in this namespace cannot be perfect because generated Javascript naming schemes produced by ClojureScript compiler were not designed with easy reversibility in mind. We recommend this functionality to be used for presentation in the UI only. The goal here is to provide user with more familiar view of runtime state of her app in most common cases (on best effort basis).

Our main weapons in this uneven fight are:

1. munged function names as they appear in Javascript (generated by ClojureScript)
2. we can also analyze function sources accessible via .toString
3. special cljs$core$IFn$_invoke protocol props generated for multi-arity functions

We can also cheat and look at runtime state of browser environment to determine some answers about namespaces.

This code can be used only in non-advanced builds!

If you discovered breakage or a new case which should be covered by this code, please open an issue: https://github.com/binaryage/cljs-devtools/issues

args-lists-to-strings cljs

(args-lists-to-strings args-lists spacer-symbol multi-arity-symbol rest-symbol)

Converts a list of arguments lists into a list of strings suitable for UI presentation.

arities-key-comparator cljs

(arities-key-comparator x y)

numbers go first (ordered), then keywords (ordered by name), and then ::variadic sticks last

arities-to-args-lists cljs

(arities-to-args-lists arities & [humanize?])

Given a map of arity functions. Tries to parse individual functions and prepare an arguments list for each arity. Returned list of arguments list is sorted by arity count, variadic arity goes last if available.

The function also optionally humanizes argument names in each arguments list if requested.

arities-to-args-lists* cljs

(arities-to-args-lists* arities)

arity-keywords-comparator cljs

(arity-keywords-comparator x y)

::variadic goes last, other keywords compare by name.

break-and-demunge-name cljs

(break-and-demunge-name munged-name)

(break-and-demunge-name munged-name ns-detector)

Given a munged-name from Javascript lands attempts to break it into a namespace part and remaining short name. Then applies appropriate demunging on them and returns ClojureScript versions of the names.

break-munged-name cljs

(break-munged-name munged-name)

(break-munged-name munged-name ns-detector)

Given a munged-name from Javascript lands attempts to break it into: [fn-ns fn-name protocol-ns protocol-name protocol-method arity].

Protocol and arity elements are optional. Function elements are always present or "".

examples for input: cljs$core$rest => ['cljs.core', 'rest'] cljs.core.reduce$cljs$core$IFn$_invoke$arity$3 => ['cljs.core' 'reduce' 'cljs.core' 'IFn' '_invoke' 3]

char-to-subscript cljs

(char-to-subscript char)

Given a character with a single digit converts it into a subscript character. Zero chracter maps to unicode 'SUBSCRIPT ZERO' (U+2080).

char-to-superscript cljs

(char-to-superscript char)

Given a character with a single digit converts it into a superscript character. Zero chracter maps to unicode 'SUPERSCRIPT ZERO' (U+2070).

cljs-fn-name? cljs

(cljs-fn-name? munged-name)

Given a Javascript name answers if the name was likely generated by ClojureScript. We use a simple heuristic here: The name must contain at least two separate dollars because we assume two-segment namespaces.

cljs-fn? cljs

(cljs-fn? f)

Given a Javascript function object returns true if the function looks like a ClojureScript function.

Uses various heuristics:

1. must be fn? (is javascript function or satisfies Fn and IFn protocols)
2. and name must be cljs-fn-name? (name can come from f.name or parsed out of function source)
3. or if anonymous function, must be non-trivial

collect-fn-arities cljs

(collect-fn-arities f)

Given a Javascript function object, tries to inspect known arity properties generated by ClojureScript compiler and collects all available arity functions into a map. Arities are keyed by arity count and variadic arity gets ::variadic key.

collect-fn-fixed-arities cljs

(collect-fn-fixed-arities f max-arity)

collect-fn-variadic-arities cljs

(collect-fn-variadic-arities f)

collect-protocol-methods cljs

(collect-protocol-methods obj protocol-selector)

common-protocol? cljs

(common-protocol? protocol-ns protocol-name)

convert-to-protocol-descriptor cljs

(convert-to-protocol-descriptor fast? [ns name selector])

demunge-protocol-selector cljs

(demunge-protocol-selector protocol-selector)

detect-namespace-prefix cljs

(detect-namespace-prefix tokens & [ns-detector])

Given a name broken into namespace parts returns [detected-ns remaining-parts], where detected-ns is a string representing longest detected existing namespace and remaining-parts is a vector of remaing input parts not included in the detected-ns concatenation.

For given input ["cljs" "core" "first"] returns ["cljs.core" ["first"]] (asumming cljs.core exists)

dollar-preserving-demunge cljs

(dollar-preserving-demunge munged-name)

Standard cljs.core/demunge is too agresive in replacing dollars. This wrapper function works around it by leaving dollars intact.

dollar-replacement cljs

extract-arities cljs

(extract-arities f humanize? spacer-symbol multi-arity-symbol rest-symbol)

fast-path-protocols-lookup-table cljs

find-index-of-human-prefix cljs

(find-index-of-human-prefix name)

Given a demunged ClojureScript parameter name. Tries to detect human readable part and returns the index where it ends. Returns nil if no prefix can be detected.

The idea is to convert macro-generated parameters and other generated names to more friendly names. We observed that param names generated by gensym have prefix followed by big numbers. Other generated names contain two dashes after prefix (originally probably using underscores).

get-basis cljs

(get-basis f)

get-fast-path-protocol-partitions-count clj/s macro

(get-fast-path-protocol-partitions-count)

get-fast-path-protocols clj/s macro

(get-fast-path-protocols)

get-fast-path-protocols-lookup-table clj/s macro

(get-fast-path-protocols-lookup-table)

get-fn-fixed-arity cljs

(get-fn-fixed-arity f n)

get-fn-max-fixed-arity cljs

(get-fn-max-fixed-arity f)

get-fn-source-safely cljs

(get-fn-source-safely f)

get-fn-variadic-arity cljs

(get-fn-variadic-arity f)

get-global-scope cljs

(get-global-scope)

get-protocol-info clj

(get-protocol-info protocol)

get-protocol-object cljs

(get-protocol-object protocol-selector)

get-protocol-selector cljs

(get-protocol-selector key)

get-type-name cljs

(get-type-name t)

humanize-name cljs

(humanize-name state name)

Given a name and intermediate state. Convert name to a human readable version by keeping human readable prefix with optional subscribt postfix and store it in ::result. Subscript number is picked based on state. State keeps track of previously assigned subscripts. Returns a new state.

humanize-names cljs

(humanize-names names)

Given a list of names, returns a list of human-readable versions of those names. It detects human-readable prefix using a simple heuristics. When names repeat it assigns simple subscripts starting with 2. Subscripts are assigned left-to-right.

Given ["p--a" "p--b" "x" "p--c"] returns ["p" "p₂" "x" "p₃"]

js-reserved? cljs

(js-reserved? x)

key-for-protocol-partition cljs

(key-for-protocol-partition partition)

make-protocol-descriptor cljs

(make-protocol-descriptor ns name selector fast?)

make-subscript cljs

(make-subscript subscript)

Given a subscript number converts it into a string representation consisting of unicode subscript characters (digits).

make-superscript cljs

(make-superscript superscript)

Given a superscript number converts it into a string representation consisting of unicode superscript characters (digits).

max-fixed-arity-to-scan cljs

normalize-arity cljs

(normalize-arity arity-tokens)

ns-exists? cljs

(ns-exists? ns-module-name)

parse-constructor-info cljs

(parse-constructor-info f)

Given a Javascript constructor function tries to retrieve [ns name basis]. Returns nil if not a cljs type.

parse-fn-info cljs

(parse-fn-info f)

Given Javascript function object tries to retrieve [ns name & args] as in parse-fn-source-info (on best effort basis).

parse-fn-info-deep cljs

(parse-fn-info-deep f)

Given a Javascript function object tries to retrieve [ns name & args] as in parse-fn-info (on best effort basis).

The difference from parse-fn-info is that this function prefers to read args from arities if available. It recurses arbitrary deep following IFn protocol leads.

If we hit multi-arity situation in leaf, we don't attempt to list arguments and return ::multi-arity placeholder instead.

The reason for reading arities is that it gives more accurate parameter names in some cases. We observed that variadic functions don't always contain original parameter names, but individual IFn arity functions do.

parse-fn-source cljs

(parse-fn-source fn-source)

Given a function source code parses out [name args]. Note that both strings are still munged. Suitable for further processing.

For exampe for input below the function will return ["devtools_sample$core$hello" "name, unused_param"]:

function devtools_sample$core$hello(name, unused_param){ return [cljs.core.str("hello, "),cljs.core.str(name),cljs.core.str("!")].join(''); }

parse-fn-source-info cljs

(parse-fn-source-info fn-source)

Given function source code tries to retrieve [ns name & args] on best effort basis, where ns is demunged namespace part of the function name (or "" if namespace cannot be detected) name is demunged short name (or "" if function is anonymous or name cannot be retrieved) args is optional number of demunged argument names.

Please note that this function always returns a vector with something. In worst cases ["" ""].

parse-protocol cljs

(parse-protocol tokens detector)

present-fn-part cljs

(present-fn-part fn-ns fn-name include-ns?)

present-function-name cljs

(present-function-name munged-name options)

Given javascript function name tries to present it as plain string for display in UI on best effort basis.

present-protocol-part cljs

(present-protocol-part protocol-ns
                       protocol-name
                       protocol-method
                       include-protocol-ns?)

proper-arg-demunge cljs

(proper-arg-demunge munged-arg-name)

proper-demunge cljs

(proper-demunge munged-name)

proper-ns-demunge cljs

(proper-ns-demunge munged-ns-name)

protocol-descriptors-comparator cljs

(protocol-descriptors-comparator a b)

protocol-exists? cljs

(protocol-exists? protocol-selector)

protocol-path cljs

(protocol-path protocol-selector)

reserved-aware-demunge cljs

(reserved-aware-demunge munged-name)

revert-reserved cljs

(revert-reserved s)

review-arities cljs

(review-arities arities)

Some arities can be marked as fixed arity but in fact point to a variadic-arity function. We want to detect this case and turn such improperly categorized arities to ::variadic.

review-arity cljs

(review-arity [arity arity-fn])

scan-fast-path-protocols cljs

(scan-fast-path-protocols obj)

scan-fast-path-protocols-partition cljs

(scan-fast-path-protocols-partition obj partition)

scan-protocols cljs

(scan-protocols obj)

scan-slow-path-protocols cljs

(scan-slow-path-protocols obj)

steal-fast-path-protocol-partitions-count clj

(steal-fast-path-protocol-partitions-count)

steal-fast-path-protocols clj

(steal-fast-path-protocols)

strip-arity cljs

(strip-arity tokens)

trivial-fn-source? cljs

(trivial-fn-source? fn-source)