libghc-jmacro-doc 0.6.13-3build1 / usr / share / doc / libghc-jmacro-doc / html / jmacro.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | QuasiQuotation library for programmatic generation of Javascript code.
--   
--   Javascript syntax, functional syntax, hygienic names, compile-time
--   guarantees of syntactic correctness, limited typechecking. Additional
--   documentation available at
--   <a>http://www.haskell.org/haskellwiki/Jmacro</a>
@package jmacro
@version 0.6.13

module Language.Javascript.JMacro.Types
data JType
JTNum :: JType
JTString :: JType
JTBool :: JType
JTStat :: JType
JTFunc :: [JType] -> (JType) -> JType
JTList :: JType -> JType
JTMap :: JType -> JType
JTRecord :: JType -> (Map String JType) -> JType
JTRigid :: VarRef -> (Set Constraint) -> JType
JTImpossible :: JType
JTFree :: VarRef -> JType
JTForall :: [VarRef] -> JType -> JType
data Constraint
Sub :: JType -> Constraint
Super :: JType -> Constraint
type JLocalType = ([(VarRef, Constraint)], JType)
type VarRef = (Maybe String, Int)
anyType :: TypeParser JType
parseType :: String -> Either ParseError JType
runTypeParser :: CharParser a JLocalType
instance Data.Data.Data Language.Javascript.JMacro.Types.JType
instance GHC.Show.Show Language.Javascript.JMacro.Types.JType
instance GHC.Read.Read Language.Javascript.JMacro.Types.JType
instance GHC.Classes.Ord Language.Javascript.JMacro.Types.JType
instance GHC.Classes.Eq Language.Javascript.JMacro.Types.JType
instance Data.Data.Data Language.Javascript.JMacro.Types.Constraint
instance GHC.Show.Show Language.Javascript.JMacro.Types.Constraint
instance GHC.Read.Read Language.Javascript.JMacro.Types.Constraint
instance GHC.Classes.Ord Language.Javascript.JMacro.Types.Constraint
instance GHC.Classes.Eq Language.Javascript.JMacro.Types.Constraint

module Language.Javascript.JMacro.Util
(.) :: JExpr -> String -> JExpr
(<>) :: (ToJExpr a) => JExpr -> a -> JExpr
(=:) :: ToJExpr a => JExpr -> a -> JStat
($) :: (ToJExpr a, ToJExpr b) => a -> b -> JExpr
($$) :: (ToJExpr a, ToJExpr b) => a -> b -> JStat
(==) :: JExpr -> JExpr -> JExpr
(!=) :: JExpr -> JExpr -> JExpr
(<) :: JExpr -> JExpr -> JExpr
(&&) :: JExpr -> JExpr -> JExpr
null :: JExpr
new :: ToJExpr a => a -> JExpr
if' :: (ToJExpr a, ToStat b) => a -> b -> JStat
ifElse :: (ToJExpr a, ToStat b, ToStat c) => a -> b -> c -> JStat
while :: ToJExpr a => a -> JStat -> JStat
return :: ToJExpr a => a -> JStat
toJExprList :: ToJExpr a => a -> [JExpr]
jstr :: String -> JExpr

module Language.Javascript.JMacro.TypeCheck
eitherIsLeft :: Either a b -> Bool
partitionOut :: (a -> Maybe b) -> [a] -> ([b], [a])
zipWithOrChange :: (a -> a -> b) -> (a -> b) -> [a] -> [a] -> [b]
zipWithOrIdM :: Monad m => (a -> a -> m a) -> [a] -> [a] -> m [a]
unionWithM :: (Monad m, Ord key) => (val -> val -> m val) -> Map key val -> Map key val -> m (Map key val)
intersectionWithM :: (Monad m, Ord key) => (val -> val -> m b) -> Map key val -> Map key val -> m (Map key b)
class Compos1 t
compos1 :: Compos1 t => (forall a. a -> m a) -> (forall a b. m (a -> b) -> m a -> m b) -> (t -> m t) -> t -> m t
composOp1 :: Compos1 t => (t -> t) -> t -> t
composOpM1 :: (Compos1 t, Monad m) => (t -> m t) -> t -> m t
composOpM1_ :: (Compos1 t, Monad m) => (t -> m ()) -> t -> m ()
composOpFold1 :: Compos1 t => b -> (b -> b -> b) -> (t -> b) -> t -> b
newtype C b a
C :: b -> C b a
[unC] :: C b a -> b
data StoreVal
SVType :: JType -> StoreVal
SVConstrained :: (Set Constraint) -> StoreVal
data TCState
TCS :: [Map Ident JType] -> Map Int StoreVal -> [Set Int] -> Set Int -> Int -> [TMonad String] -> TCState
[tc_env] :: TCState -> [Map Ident JType]
[tc_vars] :: TCState -> Map Int StoreVal
[tc_stack] :: TCState -> [Set Int]
[tc_frozen] :: TCState -> Set Int
[tc_varCt] :: TCState -> Int
[tc_context] :: TCState -> [TMonad String]
tcStateEmpty :: TCState
newtype TMonad a
TMonad :: (ErrorT String (State TCState) a) -> TMonad a
class JTypeCheck a
typecheck :: JTypeCheck a => a -> TMonad JType
evalTMonad :: TMonad a -> Either String a
runTMonad :: TMonad a -> (Either String a, TCState)
withContext :: TMonad a -> TMonad String -> TMonad a
traversem_ :: (Foldable t, Monad f) => (a -> f b) -> t a -> f ()
freeVarsWithNames :: JType -> TMonad (Map Int String)
prettyType :: JType -> TMonad String
tyErr0 :: String -> TMonad a
tyErr1 :: String -> JType -> TMonad b
tyErr2ext :: String -> String -> String -> JType -> JType -> TMonad a
tyErr2Sub :: JType -> JType -> TMonad a
prettyEnv :: TMonad [Map Ident String]
runTypecheckRaw :: JTypeCheck a => a -> (Either String JType, TCState)
runTypecheckFull :: JTypeCheck a => a -> (Either String (String, [Map Ident String]), TCState)
runTypecheck :: JTypeCheck a => a -> Either String String
evalTypecheck :: JTypeCheck a => a -> Either String [Map Ident String]
typecheckMain :: JTypeCheck a => a -> TMonad JType
addToStack :: Ord a => a -> [Set a] -> [Set a]
newVarRef :: TMonad VarRef
newTyVar :: TMonad JType
mapConstraint :: (Monad m, Functor m) => (JType -> m JType) -> Constraint -> m Constraint
partitionCs :: [Constraint] -> ([JType], [JType])
lookupConstraintsList :: VarRef -> TMonad [Constraint]
instantiateVarRef :: VarRef -> JType -> TMonad ()
occursCheck :: Int -> JType -> TMonad ()
checkConstraints :: JType -> [Constraint] -> TMonad ()
addConstraint :: VarRef -> Constraint -> TMonad ()
cannonicalizeConstraints :: [Constraint] -> TMonad [Constraint]
tryCloseFrozenVars :: TMonad ()
withLocalScope :: TMonad a -> TMonad (a, Set Int)
setFrozen :: Set Int -> TMonad ()
frame2VarRefs :: Set t -> [(Maybe a, t)]
addEnv :: Ident -> JType -> TMonad ()
newVarDecl :: Ident -> TMonad JType
resolveTypeGen :: ((JType -> TMonad JType) -> JType -> TMonad JType) -> JType -> TMonad JType
resolveType :: JType -> TMonad JType
resolveTypeShallow :: JType -> TMonad JType
integrateLocalType :: JLocalType -> TMonad JType
lookupEnv :: Ident -> TMonad JType
freeVars :: JType -> TMonad (Set Int)
instantiateScheme :: [VarRef] -> JType -> TMonad JType
instantiateRigidScheme :: [VarRef] -> JType -> TMonad JType
checkEscapedVars :: [VarRef] -> JType -> TMonad ()
(<:) :: JType -> JType -> TMonad ()
(<<:>) :: TMonad JType -> TMonad JType -> TMonad ()
someUpperBound :: [JType] -> TMonad JType
someLowerBound :: [JType] -> TMonad JType
(=.=) :: JType -> JType -> TMonad JType
typecheckWithBlock :: (JsToDoc a, JMacro a, JTypeCheck a) => a -> TMonad JType
instance Control.Monad.Error.Class.MonadError GHC.Base.String Language.Javascript.JMacro.TypeCheck.TMonad
instance Control.Monad.State.Class.MonadState Language.Javascript.JMacro.TypeCheck.TCState Language.Javascript.JMacro.TypeCheck.TMonad
instance GHC.Base.Monad Language.Javascript.JMacro.TypeCheck.TMonad
instance GHC.Base.Functor Language.Javascript.JMacro.TypeCheck.TMonad
instance GHC.Show.Show Language.Javascript.JMacro.TypeCheck.StoreVal
instance Language.Javascript.JMacro.TypeCheck.Compos1 Language.Javascript.JMacro.Types.JType
instance GHC.Show.Show Language.Javascript.JMacro.TypeCheck.TCState
instance GHC.Base.Applicative Language.Javascript.JMacro.TypeCheck.TMonad
instance Language.Javascript.JMacro.TypeCheck.JTypeCheck Language.Javascript.JMacro.Base.JExpr
instance Language.Javascript.JMacro.TypeCheck.JTypeCheck Language.Javascript.JMacro.Base.JVal
instance Language.Javascript.JMacro.TypeCheck.JTypeCheck Language.Javascript.JMacro.Base.JStat


module Language.Javascript.JMacro.Prelude

-- | This provides a set of basic functional programming primitives, a few
--   utility functions and, more importantly, a decent sample of idiomatic
--   jmacro code. View the source for details.
jmPrelude :: JStat


-- | Simple DSL for lightweight (untyped) programmatic generation of
--   Javascript.
--   
--   A number of examples are available in the source of
--   <a>Language.Javascript.JMacro.Prelude</a>.
--   
--   Functions to generate generic RPC wrappers (using json serialization)
--   are available in <a>Language.Javascript.JMacro.Rpc</a>.
--   
--   usage:
--   
--   <pre>
--   renderJs [$jmacro|fun id x -&gt; x|]
--   </pre>
--   
--   The above produces the id function at the top level.
--   
--   <pre>
--   renderJs [$jmacro|var id = \x -&gt; x;|]
--   </pre>
--   
--   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.
--   
--   <pre>
--   renderJs [$jmacro|var !id = \x -&gt; x;|]
--   </pre>
--   
--   The above, by using the bang special form in a var declaration,
--   produces a variable that really is named id.
--   
--   <pre>
--   renderJs [$jmacro|function id(x) {return x;}|]
--   </pre>
--   
--   The above is also id.
--   
--   <pre>
--   renderJs [$jmacro|function !id(x) {return x;}|]
--   </pre>
--   
--   As is the above (with the correct name).
--   
--   <pre>
--   renderJs [$jmacro|fun id x {return x;}|]
--   </pre>
--   
--   As is the above.
--   
--   <pre>
--   renderJs [$jmacroE|foo(x,y)|]
--   </pre>
--   
--   The above is an expression representing the application of foo to x
--   and y.
--   
--   <pre>
--   renderJs [$jmacroE|foo x y|]]
--   </pre>
--   
--   As is the above.
--   
--   <pre>
--   renderJs [$jmacroE|foo (x,y)|]
--   </pre>
--   
--   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)
--   
--   <pre>
--   \x -&gt; [$jmacroE|foo `(x)`|]
--   </pre>
--   
--   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.
--   
--   <pre>
--   [$jmacroE|\x -&gt;`(foo x)`|]
--   </pre>
--   
--   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. <tt>x <i> 5 </i> 4</tt> parses as ((x <i> 5) </i> 4). However,
--   <tt>x <i>5 </i> 4</tt> will parse as x(<i>5 </i>, 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
--   <a>Language.Javascript.JMacro.Typed</a> module.
module Language.Javascript.JMacro

-- | QuasiQuoter for a block of JMacro statements.
jmacro :: QuasiQuoter

-- | QuasiQuoter for a JMacro expression.
jmacroE :: QuasiQuoter
parseJM :: String -> Either ParseError JStat
parseJME :: String -> Either ParseError JExpr

-- | Statements
data JStat
DeclStat :: Ident -> (Maybe JLocalType) -> JStat
ReturnStat :: JExpr -> JStat
IfStat :: JExpr -> JStat -> JStat -> JStat
WhileStat :: Bool -> JExpr -> JStat -> JStat
ForInStat :: Bool -> Ident -> JExpr -> JStat -> JStat
SwitchStat :: JExpr -> [(JExpr, JStat)] -> JStat -> JStat
TryStat :: JStat -> Ident -> JStat -> JStat -> JStat
BlockStat :: [JStat] -> JStat
ApplStat :: JExpr -> [JExpr] -> JStat
PPostStat :: Bool -> String -> JExpr -> JStat
AssignStat :: JExpr -> JExpr -> JStat
UnsatBlock :: (IdentSupply JStat) -> JStat
AntiStat :: String -> JStat
ForeignStat :: Ident -> JLocalType -> JStat
LabelStat :: JsLabel -> JStat -> JStat
BreakStat :: (Maybe JsLabel) -> JStat
ContinueStat :: (Maybe JsLabel) -> JStat

-- | Expressions
data JExpr
ValExpr :: JVal -> JExpr
SelExpr :: JExpr -> Ident -> JExpr
IdxExpr :: JExpr -> JExpr -> JExpr
InfixExpr :: String -> JExpr -> JExpr -> JExpr
PPostExpr :: Bool -> String -> JExpr -> JExpr
IfExpr :: JExpr -> JExpr -> JExpr -> JExpr
NewExpr :: JExpr -> JExpr
ApplExpr :: JExpr -> [JExpr] -> JExpr
UnsatExpr :: (IdentSupply JExpr) -> JExpr
AntiExpr :: String -> JExpr
TypeExpr :: Bool -> JExpr -> JLocalType -> JExpr

-- | Values
data JVal
JVar :: Ident -> JVal
JList :: [JExpr] -> JVal
JDouble :: SaneDouble -> JVal
JInt :: Integer -> JVal
JStr :: String -> JVal
JRegEx :: String -> JVal
JHash :: (Map String JExpr) -> JVal
JFunc :: [Ident] -> JStat -> JVal
UnsatVal :: (IdentSupply JVal) -> JVal

-- | Identifiers
newtype Ident
StrI :: String -> Ident
newtype IdentSupply a
IS :: State [Ident] a -> IdentSupply a
[runIdentSupply] :: IdentSupply a -> State [Ident] a
type JsLabel = String

-- | Compos and ops for generic traversal as defined over the JMacro ADT.
--   
--   Utility class to coerce the ADT into a regular structure.
class JMacro a
jtoGADT :: JMacro a => a -> JMGadt a
jfromGADT :: JMacro a => JMGadt a -> a

-- | Union type to allow regular traversal by compos.
data JMGadt a
JMGId :: Ident -> JMGadt Ident
JMGStat :: JStat -> JMGadt JStat
JMGExpr :: JExpr -> JMGadt JExpr
JMGVal :: JVal -> JMGadt JVal
class Compos t
compos :: Compos t => (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)
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

-- | 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.
withHygiene :: JMacro a => (a -> a) -> a -> a

-- | Takes a fully saturated expression and transforms it to use unique
--   variables that respect scope.
scopify :: JStat -> JStat

-- | Render a syntax tree as a pretty-printable document (simply showing
--   the resultant doc produces a nice, well formatted String).
renderJs :: (JsToDoc a, JMacro a) => 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.
renderPrefixJs :: (JsToDoc a, JMacro a) => String -> a -> Doc
class JsToDoc a
jsToDoc :: JsToDoc a => a -> Doc

-- | Things that can be marshalled into javascript values. Instantiate for
--   any necessary data structures.
class ToJExpr a where toJExprFromList = ValExpr . JList . map toJExpr
toJExpr :: ToJExpr a => a -> JExpr
toJExprFromList :: ToJExpr a => [a] -> JExpr
jsv :: String -> JExpr

-- | Create a new anonymous function. The result is an expression. Usage:
--   <tt>jLam $ x y -&gt; {JExpr involving x and y}</tt>
jLam :: (ToSat a) => a -> JExpr

-- | Introduce a new variable into scope for the duration of the enclosed
--   expression. The result is a block statement. Usage: <tt>jVar $ x y
--   -&gt; {JExpr involving x and y}</tt>
jVar :: (ToSat a) => a -> JStat

-- | Introduce a new variable with optional type into scope for the
--   duration of the enclosed expression. The result is a block statement.
--   Usage: <tt>jVar $ x y -&gt; {JExpr involving x and y}</tt>
jVarTy :: (ToSat a) => a -> (Maybe JLocalType) -> JStat
jFor :: (ToJExpr a, ToStat b) => JStat -> a -> JStat -> b -> JStat

-- | Create a for in statement. Usage: <tt>jForIn {expression} $ x -&gt;
--   {block involving x}</tt>
jForIn :: ToSat a => JExpr -> (JExpr -> a) -> JStat

-- | As with "jForIn" but creating a "for each in" statement.
jForEachIn :: ToSat a => JExpr -> (JExpr -> a) -> JStat
jTryCatchFinally :: (ToSat a) => JStat -> a -> JStat -> JStat
expr2stat :: JExpr -> JStat
class ToStat a
toStat :: ToStat a => a -> JStat
nullStat :: JStat
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

-- | Given an optional prefix, fills in all free variable names with a
--   supply of names generated by the prefix.
jsSaturate :: (JMacro a) => Maybe String -> a -> a
jtFromList :: JType -> [(String, JType)] -> JType
newtype SaneDouble
SaneDouble :: Double -> SaneDouble