Language.Javascript.JMacro

Simple DSL for lightweight (untyped) programmatic generation of Javascript.

A number of examples are available in the source of Language.Javascript.JMacro.Prelude.

Functions to generate generic RPC wrappers (using json serialization) are available in Language.Javascript.JMacro.Rpc.

usage:

renderJs [jmacro|fun id x -> x|]

The above produces the id function at the top level.

renderJs [jmacro|var id = \x -> x;|]

So does the above here. However, as id is brought into scope by the keyword var, you do not get a variable named id in the generated javascript, but a variable with an arbitrary unique identifier.

renderJs [jmacro|var !id = \x -> x;|]

The above, by using the bang special form in a var declaration, produces a variable that really is named id.

renderJs [jmacro|function id(x) {return x;}|]

The above is also id.

renderJs [jmacro|function !id(x) {return x;}|]

As is the above (with the correct name).

renderJs [jmacro|fun id x {return x;}|]

As is the above.

renderJs [jmacroE|foo(x,y)|]

The above is an expression representing the application of foo to x and y.

renderJs [jmacroE|foo x y|]]

As is the above.

renderJs [jmacroE|foo (x,y)|]

While the above is an error. (i.e. standard javascript function application cannot seperate the leading parenthesis of the argument from the function being applied)

\x -> [jmacroE|foo `(x)`|]

The above is a haskell expression that provides a function that takes an x, and yields an expression representing the application of foo to the value of x as transformed to a Javascript expression.

[jmacroE|\x ->`(foo x)`|]

Meanwhile, the above lambda is in Javascript, and brings the variable into scope both in javascript and in the enclosed antiquotes. The expression is a Javascript function that takes an x, and yields an expression produced by the application of the Haskell function foo as applied to the identifier x (which is of type JExpr -- i.e. a Javascript expression).

Other than that, the language is essentially Javascript (1.5). Note however that one must use semicolons in a principled fashion -- i.e. to end statements consistently. Otherwise, the parser will mistake the whitespace for a whitespace application, and odd things will occur. A further gotcha exists in regex literals, whicch cannot begin with a space. x 5 4 parses as ((x 5) 4). However, x 5 4 will parse as x(5 , 4). Such are the perils of operators used as delimeters in the presence of whitespace application.

Additional features in jmacro (documented on the wiki) include an infix application operator, and an enhanced destructuring bind.

Additional datatypes can be marshalled to Javascript by proper instance declarations for the ToJExpr class.

An experimental typechecker is available in the Language.Javascript.JMacro.Typed module.

Documentation

jmacro :: QuasiQuoter

QuasiQuoter for a block of JMacro statements.

jmacroE :: QuasiQuoter

QuasiQuoter for a JMacro expression.

parseJM :: String -> Either ParseError JStat

parseJME :: String -> Either ParseError JExpr

ADT

data JStat

Statements

Constructors

DeclStat Ident (Maybe JLocalType)

ReturnStat JExpr

IfStat JExpr JStat JStat

WhileStat Bool JExpr JStat

ForInStat Bool Ident JExpr JStat

SwitchStat JExpr [(JExpr, JStat)] JStat

TryStat JStat Ident JStat JStat

BlockStat [JStat]

ApplStat JExpr [JExpr]

PPostStat Bool String JExpr

AssignStat JExpr JExpr

UnsatBlock (IdentSupply JStat)

AntiStat String

ForeignStat Ident JLocalType

LabelStat JsLabel JStat

BreakStat (Maybe JsLabel)

ContinueStat (Maybe JsLabel)

Instances

Eq JStat

Data JStat

Ord JStat

Show JStat

Monoid JStat

ToStat JStat

JsToDoc JStat

JMacro JStat

JTypeCheck JStat

ToStat [JStat]

JsToDoc [JStat]

data JExpr

Expressions

Constructors

ValExpr JVal

SelExpr JExpr Ident

IdxExpr JExpr JExpr

InfixExpr String JExpr JExpr

PPostExpr Bool String JExpr

IfExpr JExpr JExpr JExpr

NewExpr JExpr

ApplExpr JExpr [JExpr]

UnsatExpr (IdentSupply JExpr)

AntiExpr String

TypeExpr Bool JExpr JLocalType

Instances

Eq JExpr

Data JExpr

Num JExpr

Ord JExpr

Show JExpr

ToStat JExpr

ToJExpr JExpr

JsToDoc JExpr

JMacro JExpr

JTypeCheck JExpr

ToStat [JExpr]

JsToDoc [JExpr]

data JVal

Values

Constructors

JVar Ident

JList [JExpr]

JDouble SaneDouble

JInt Integer

JStr String

JRegEx String

JHash (Map String JExpr)

JFunc [Ident] JStat

UnsatVal (IdentSupply JVal)

Instances

Eq JVal

Data JVal

Ord JVal

Show JVal

ToJExpr JVal

JsToDoc JVal

JMacro JVal

JTypeCheck JVal

newtype Ident

Identifiers

Constructors

StrI String

Instances

Eq Ident

Data Ident

Ord Ident

Show Ident

JsToDoc Ident

JMacro Ident

newtype IdentSupply a

Constructors

IS

Fields

runIdentSupply :: State [Ident] a

Instances

Functor IdentSupply

Eq a => Eq (IdentSupply a)

Data a => Data (IdentSupply a)

Ord a => Ord (IdentSupply a)

Show a => Show (IdentSupply a)

type JsLabel = String

Generic traversal (via compos)

class JMacro a where

Compos and ops for generic traversal as defined over the JMacro ADT.

Utility class to coerce the ADT into a regular structure.

Methods

jtoGADT :: a -> JMGadt a

jfromGADT :: JMGadt a -> a

Instances

JMacro Ident

JMacro JVal

JMacro JExpr

JMacro JStat

data JMGadt a where

Union type to allow regular traversal by compos.

Constructors

JMGId :: Ident -> JMGadt Ident

JMGStat :: JStat -> JMGadt JStat

JMGExpr :: JExpr -> JMGadt JExpr

JMGVal :: JVal -> JMGadt JVal

Instances

Compos JMGadt

class Compos t where

Methods

compos :: (forall a. a -> m a) -> (forall a b. m (a -> b) -> m a -> m b) -> (forall a. t a -> m (t a)) -> t c -> m (t c)

Instances

Compos JMGadt

composOp :: Compos t => (forall a. t a -> t a) -> t b -> t b

composOpM :: (Compos t, Monad m) => (forall a. t a -> m (t a)) -> t b -> m (t b)

composOpM_ :: (Compos t, Monad m) => (forall a. t a -> m ()) -> t b -> m ()

composOpFold :: Compos t => b -> (b -> b -> b) -> (forall a. t a -> b) -> t c -> b

Hygienic transformation

withHygiene :: JMacro a => (a -> a) -> a -> a

Apply a transformation to a fully saturated syntax tree, taking care to return any free variables back to their free state following the transformation. As the transformation preserves free variables, it is hygienic.

scopify :: JStat -> JStat

Takes a fully saturated expression and transforms it to use unique variables that respect scope.

Display/Output

renderJs :: (JsToDoc a, JMacro a) => a -> Doc

Render a syntax tree as a pretty-printable document (simply showing the resultant doc produces a nice, well formatted String).

renderPrefixJs :: (JsToDoc a, JMacro a) => String -> a -> Doc

Render a syntax tree as a pretty-printable document, using a given prefix to all generated names. Use this with distinct prefixes to ensure distinct generated names between independent calls to render(Prefix)Js.

class JsToDoc a where

Methods

jsToDoc :: a -> Doc

Instances

JsToDoc JLocalType

JsToDoc JType

JsToDoc Ident

JsToDoc JVal

JsToDoc JExpr

JsToDoc JStat

JsToDoc [JExpr]

JsToDoc [JStat]

Ad-hoc data marshalling

class ToJExpr a where

Things that can be marshalled into javascript values. Instantiate for any necessary data structures.

Minimal complete definition

toJExpr

Methods

toJExpr :: a -> JExpr

toJExprFromList :: [a] -> JExpr

Instances

ToJExpr Bool

ToJExpr Char

ToJExpr Double

ToJExpr Int

ToJExpr Integer

ToJExpr ()

ToJExpr Text

ToJExpr Value

ToJExpr Text

ToJExpr JVal

ToJExpr JExpr

ToJExpr a => ToJExpr [a]

(ToJExpr a, ToJExpr b) => ToJExpr (a, b)

ToJExpr a => ToJExpr (Map String a)

(ToJExpr a, ToJExpr b, ToJExpr c) => ToJExpr (a, b, c)

(ToJExpr a, ToJExpr b, ToJExpr c, ToJExpr d) => ToJExpr (a, b, c, d)

(ToJExpr a, ToJExpr b, ToJExpr c, ToJExpr d, ToJExpr e) => ToJExpr (a, b, c, d, e)

(ToJExpr a, ToJExpr b, ToJExpr c, ToJExpr d, ToJExpr e, ToJExpr f) => ToJExpr (a, b, c, d, e, f)

Literals

jsv :: String -> JExpr

Occasionally helpful combinators

jLam :: ToSat a => a -> JExpr

Create a new anonymous function. The result is an expression. Usage: jLam $ x y -> {JExpr involving x and y}

jVar :: ToSat a => a -> JStat

Introduce a new variable into scope for the duration of the enclosed expression. The result is a block statement. Usage: jVar $ x y -> {JExpr involving x and y}

jVarTy :: ToSat a => a -> Maybe JLocalType -> JStat

Introduce a new variable with optional type into scope for the duration of the enclosed expression. The result is a block statement. Usage: jVar $ x y -> {JExpr involving x and y}

jFor :: (ToJExpr a, ToStat b) => JStat -> a -> JStat -> b -> JStat

jForIn :: ToSat a => JExpr -> (JExpr -> a) -> JStat

Create a for in statement. Usage: jForIn {expression} $ x -> {block involving x}

jForEachIn :: ToSat a => JExpr -> (JExpr -> a) -> JStat

As with "jForIn" but creating a "for each in" statement.

jTryCatchFinally :: ToSat a => JStat -> a -> JStat -> JStat

expr2stat :: JExpr -> JStat

class ToStat a where

Methods

toStat :: a -> JStat

Instances

ToStat JExpr

ToStat JStat

ToStat [JExpr]

ToStat [JStat]

nullStat :: JStat

Hash combinators

jhEmpty :: Map String JExpr

jhSingle :: ToJExpr a => String -> a -> Map String JExpr

jhAdd :: ToJExpr a => String -> a -> Map String JExpr -> Map String JExpr

jhFromList :: [(String, JExpr)] -> JVal

Utility

jsSaturate :: JMacro a => Maybe String -> a -> a

Given an optional prefix, fills in all free variable names with a supply of names generated by the prefix.

jtFromList :: JType -> [(String, JType)] -> JType

newtype SaneDouble

Constructors

SaneDouble Double

Instances

Eq SaneDouble

Fractional SaneDouble

Data SaneDouble

Num SaneDouble

Ord SaneDouble

Show SaneDouble

module Language.Javascript.JMacro.Prelude

module Language.Javascript.JMacro.Types