diff --git a/js-good-parts.cabal b/js-good-parts.cabal --- a/js-good-parts.cabal +++ b/js-good-parts.cabal @@ -1,5 +1,5 @@ Name: js-good-parts -Version: 0.0.1 +Version: 0.0.2 Cabal-Version: >= 1.6 Synopsis: Javascript: The Good Parts -- AST & Pretty Printer Category: Language, Javascript @@ -10,7 +10,7 @@ Author: Sean Seefried Maintainer: sean.seefried@gmail.com -Homepage: http://github.com/sseefried/js-good-parts.git +Homepage: https://github.com/sseefried/js-good-parts.git Copyright: (c) by Sean Seefried License: BSD3 License-File: LICENSE @@ -18,7 +18,7 @@ build-type: Simple Source-Repository head type: git - location: git://github.com/sseefried/js-tgp.git + location: https://github.com/sseefried/js-good-parts.git Library hs-Source-Dirs: src @@ -27,3 +27,4 @@ Exposed-Modules: Language.JavaScript.AST Language.JavaScript.Pretty + Other-Modules: Language.JavaScript.NonEmptyList diff --git a/src/Language/JavaScript/AST.hs b/src/Language/JavaScript/AST.hs --- a/src/Language/JavaScript/AST.hs +++ b/src/Language/JavaScript/AST.hs @@ -5,10 +5,10 @@ -- -- © 2012 -- --- In Chapter 2 of "JavaScript: The Good Parts", Douglas Crockford presents a --- concrete grammar for "the good parts" of JavaScript. +-- | In Chapter 2 of \"JavaScript: The Good Parts\", Douglas Crockford presents a +-- concrete grammar for \"the good parts\" of JavaScript. -- --- This module provides an abstract grammar for those good parts. We will abbreviate this +-- This module provides an abstract grammar for those good parts. Henceforth, we abbreviate this -- language to JS:TGP -- -- Crockford presents the grammar as a series of railroad diagrams. @@ -18,43 +18,40 @@ -- For each valid program produced by the concrete grammar there is a corresponding -- abstract syntax tree that when pretty printed will produce that program (modulo whitespace). -- --- The abstract grammar: +-- /The abstract grammar/ +-- -- * removes unnecessary characters such as parentheses (normal, curly and square) +-- -- * represents JavaScript's string, name and number literals directly in Haskell as -- 'String', 'String' and 'Double' respectively. -- --- Conventions for concrete syntax: --- - Non-terminals appear in angle brackets e.g. --- - ? means zero or one. e.g. ? --- - * means zero or more e.g. * --- - + means one or more e.g. + --- - \( \) are meta-brackets used to enclose a concrete-syntax expression so that ?,* or + --- can be applied. e.g. \(= \)* --- This means zero or more repetitions of: = +-- /Conventions for concrete syntax/ -- --- The data structure ensures no incorrect JS:TGP programs --- ------------------------------------------------------- --- This library was designed so that it would be impossible, save for name, string literals --- to construct an incorrect JS:TGP program. +-- * Non-terminals appear in angle brackets e.g. \ -- --- To this end some of the data structures may look like they contain redundancy. --- For instance, consider the 'JSESDelete' constructor which is defined +-- * ? means zero or one. e.g. \? -- --- JSESDelete JSExpression JSInvocation +-- * * means zero or more e.g. \* -- --- Why not just define it as 'JSESDelete JSExpression' since type 'JSExpression' --- has a constructor defined as 'JSExpressionInvocation JSExpression JSInvocation'? +-- * + means one or more e.g. \+ +-- +-- * \( \) are meta-brackets used to enclose a concrete-syntax expression so that ?,* or + +-- can be applied. e.g. \(= \\)* +-- This means zero or more repetitions of: = \ +-- +-- This library was designed so that it would be impossible, save for name, string literals +-- to construct an incorrect JS:TGP program. To this end some of the data structures may look like +-- they contain redundancy. For instance, consider the 'JSESDelete' constructor which is defined +-- +-- @JSESDelete JSExpression JSInvocation@ +-- +-- Why not just define it as @JSESDelete JSExpression@ since type @JSExpression@ +-- has a constructor defined as @JSExpressionInvocation JSExpression JSInvocation@? -- The reason is that this would allow incorrect programs. A 'JSExpression' is --- not necessarily an invocation. +-- not necessarily a 'JSInvocation'. -- --- However, even though none of the programs are incorrect there are still some things --- it cannot check for. Although labels can appear before any statement, they should --- only be used on statements that interact with a switch, while, do, or for statement. --- This cannot be checked except by a second pass over the AST. This library does not --- provide this functionality. +-- /A note on precedence of JavaScript operators/ -- --- A note on precedence of JavaScript operators --- -------------------------------------------- -- Interestingly, the precedence of JavaScript operators is -- not defined in the ECMAScript standard. The precedence used in this library comes from -- the Mozilla Developer's Network pages. @@ -66,51 +63,58 @@ -- have been normalised to what we are using in JS:TGP -- -- You will also note that we don't even consider the associativity/precedence of --- "=", "+=", "-=" etc. In JS:TGP the notion of expression statements is quite different +-- \"=\", \"+=\", \"-=\" etc. In JS:TGP the notion of expression statements is quite different -- to that of expressions. It simply isn't legal to write an expression statement like -- --- (a += 2) -= 3 --- OR --- a = (b = c) = (c = d) +-- @(a += 2) -= 3@ -- +-- or +-- +-- @a = (b = c) = (c = d)@ +-- -- although it is perfectly legal to write -- --- a = b = c = d += 2 +-- @a = b = c = d += 2@ -- -- which if we add brackets to disambiguate is really -- --- a = (b = (c = (d += 2))) +-- @a = (b = (c = (d += 2)))@ -- -- --- Interesting aspects of "the good parts" --- --------------------------------------- +-- Interesting aspects of \"the good parts\": -- +-- -- A JS:TGP program is a collection of statements. You'll note that there is no -- statement to declare a function in JS:TGP. However you can assign a function literal -- to a variable. -- --- e.g. var fun = function(x) { return x + 1;} +-- e.g. -- +-- @var fun = function(x) { return x + 1;}@ +-- +-- -- What about recursive functions then? There is the option to give the function a name which is -- local to the literal. -- --- e.g. var factorial = function f(n) { --- if ( n > 0 ) { --- return n * f(n - 1); --- } else { --- return 1; --- } --- } +-- e.g. -- --- 'f' is local. It will not be in scope outside of the function body. +-- @var factorial = function f(n) { +-- if ( n > 0 ) { +-- return n * f(n - 1); +-- } else { +-- return 1; +-- } +-- }@ -- +-- @f@ is local. It will not be in scope outside of the function body. +-- module Language.JavaScript.AST ( -- JSString, JSName can't be create except with constructors JSString, JSName, unJSString, unJSName, jsString, jsName, - -- Data types + -- * Data types JSNumber(..), JSVarStatement(..), JSVarDecl(..), JSStatement(..), JSDisruptiveStatement(..), JSIfStatement(..), JSSwitchStatement(..), @@ -129,7 +133,7 @@ data JSName = JSName { unJSName :: String } -- --- The only way you can create a JSName +-- | 'jsName' is the only way you can create a JSName -- jsName :: String -> Either String JSName jsName = Right . JSName -- FIXME: Return Left on error. @@ -137,9 +141,9 @@ data JSString = JSString { unJSString :: String } -- --- The only way you can create a Javascript string. --- This function needs to correctly encode all special characters. --- See p9 of "JavaScript: The Good Parts" +-- | The only way you can create a Javascript string. +-- This function needs to correctly encode all special characters. +-- See p9 of \"JavaScript: The Good Parts\" -- jsString :: String -> Either String JSString jsString = Right . JSString -- FIXME: Return Left on error @@ -148,113 +152,163 @@ newtype JSNumber = JSNumber Double -- 64 bit floating point number -- --- Concrete syntax: var [, ]* ; +-- | Concrete syntax: -- --- e.g. var x = 1, y; +-- @var \ [, \]* ;@ -- +-- e.g. @var x = 1, y;@ +-- data JSVarStatement = JSVarStatement (NonEmptyList JSVarDecl) -- -- | Concrete syntax: --- 1. \(= \)? -- +-- 1. @\ \(= \\)?@ +-- -- e.g. --- 1. x --- 2. x = 2 + y -- +-- 1. @x@ +-- +-- 2. @x = 2 + y@ +-- data JSVarDecl = JSVarDecl JSName (Maybe JSExpression) -- optional initialization -- -- | The many different kinds of statements -- data JSStatement - = JSStatementExpression JSExpressionStatement -- ^ syntax: ; - | JSStatementDisruptive JSDisruptiveStatement -- ^ syntax: - | JSStatementTry JSTryStatement -- ^ syntax: - | JSStatementIf JSIfStatement -- ^ syntax: - -- | syntax: \( : \) + = JSStatementExpression JSExpressionStatement -- ^ @\;@ + | JSStatementDisruptive JSDisruptiveStatement -- ^ @\@ + | JSStatementTry JSTryStatement -- ^ @\@ + | JSStatementIf JSIfStatement -- ^ @\@ + + -- | @\(\ : \) \@ | JSStatementSwitch (Maybe JSName) JSSwitchStatement - -- | syntax: \( : \) + -- | @\(\ : \) \@ | JSStatementWhile (Maybe JSName) JSWhileStatement - -- | syntax: \( : \) + -- | @\(\ : \) \@ | JSStatementFor (Maybe JSName) JSForStatement - -- | syntax: \( : \) + -- | @\(\ : \) \@ | JSStatementDo (Maybe JSName) JSDoStatement -- -- | Disruptive statements -- data JSDisruptiveStatement - = JSDSBreak JSBreakStatement -- syntax: - | JSDSReturn JSReturnStatement -- syntax: - | JSDSThrow JSThrowStatement -- syntax: + = JSDSBreak JSBreakStatement -- ^ @\@ + | JSDSReturn JSReturnStatement -- ^ @syntax: \@ + | JSDSThrow JSThrowStatement -- ^ @syntax: \@ -- -- | Concrete syntax: --- if ( ) { * } -- for 'Nothing' --- OR --- if ( ) { * } else { * } -- for 'Just . Left' --- OR --- if ( ) { * } else -- for 'Just . Right' -- +-- @if ( \ ) { \* }@ -- for 'Nothing' +-- +-- or +-- +-- @if ( \ ) { \* } else { \* }@ -- for 'Just . Left' +-- +-- or +-- +-- @if ( \ ) { \* } else \@ -- for 'Just . Right' +-- -- e.g. --- if (x > 3) { y = 2; } --- OR --- if (x < 2) { y = 1; } else { y = 3; z = 2; } --- OR --- if (x > 0) { y = 20; } else if ( x > 10) { y = 30; } else { y = 10; } -- -data JSIfStatement = JSIfStatement JSExpression [JSStatement] (Maybe (Either [JSStatement] JSIfStatement)) +-- 1. @if (x > 3) { y = 2; }@ +-- +-- 2. @if (x < 2) { y = 1; } else { y = 3; z = 2; }@ +-- +-- 3. @if (x > 0) { y = 20; } else if ( x > 10) { y = 30; } else { y = 10; }@ +-- +data JSIfStatement = JSIfStatement JSExpression + [JSStatement] + (Maybe (Either [JSStatement] JSIfStatement)) + -- -- | Concrete syntax: --- switch ( ) { } --- OR --- switch ( ) { + --- default : * } --- e.g. --- 1. switch ( x ) { --- case 1: --- y = 2; --- } --- 2. switch ( x ) { --- case 1: --- y = 2; --- break; --- case 2: --- y = 3; --- break; --- default: --- y = 4; --- } -- +-- @switch ( \ ) { \ }@ +-- +-- or +-- +-- @ +-- switch ( \ ) { +-- \+ +-- default : \* +-- } +-- @ +-- +-- e.g. +-- +-- 1. +-- +-- @ +-- switch ( x ) { +-- case 1: +-- y = 2; +-- } +-- @ +-- +-- 2. +-- +-- @ +-- switch ( x ) { +-- case 1: +-- y = 2; +-- break; +-- case 2: +-- y = 3; +-- break; +-- default: +-- y = 4; +-- } +-- @ +-- data JSSwitchStatement = JSSwitchStatementSingleCase JSExpression JSCaseClause | JSSwitchStatement JSExpression - (NonEmptyList JSCaseAndDisruptive) -- non-default case clauses - [JSStatement] -- default clause statements + (NonEmptyList JSCaseAndDisruptive) + -- ^ non-default case clauses + [JSStatement] + -- ^ default clause statements -- -- | A case clause followed by a disruptive statement -- -- Concrete syntax: --- +-- +-- @\ \@ +-- -- e.g. --- 1. case 2: --- y = 2; --- break; -- +-- 1. +-- @ +-- case 2: +-- y = 2; +-- break; +-- @ +-- data JSCaseAndDisruptive = JSCaseAndDisruptive JSCaseClause JSDisruptiveStatement -- -- | Concrete syntax: --- case : * -- --- e.g. --- 1. case 2: // zero statements following the case expression is valid. --- 2. case 2: --- y = 1; +-- @case \ : \*@ -- +-- e.g. +-- +-- 1. +-- +-- @case 2: \/\/ zero statements following the case expression is valid.@ +-- +-- 2. +-- +-- @ +-- case 2: +-- y = 1; +-- @ +-- data JSCaseClause = JSCaseClause JSExpression [JSStatement] -- @@ -262,26 +316,43 @@ -- -- Concrete syntax: -- --- 1. for (? ; ? ; ? ) { --- * --- } --- 2. for ( in ) { --- * --- } +-- 1. -- +-- @ +-- for (\? ; \? ; \? ) { +-- \* +-- } +-- @ +-- +-- 2. +-- +-- @ +-- for ( \ in \ ) { +-- \* +-- } +-- @ +-- -- e.g. --- 1. for ( ; ; ) { } --- 2. for ( ; x < 10 ;) { x += 1; } --- 3. for (i = 0; i < 10; i += 1) { --- x += i; --- } --- 4. for ( i in indices ) { a[i] = 66; } -- +-- 1. @for ( ; ; ) { }@ +-- +-- 2. @for ( ; x < 10 ;) { x += 1; }@ +-- +-- 3. +-- +-- @ +-- for (i = 0; i < 10; i += 1) { +-- x += i; +-- } +-- @ +-- +-- 4. @for ( i in indices ) { a[i] = 66; }@ +-- data JSForStatement = JSForStatementCStyle - (Maybe JSExpressionStatement) -- initialization - (Maybe JSExpression) -- condition - (Maybe JSExpressionStatement) -- increment - [JSStatement] -- body + (Maybe JSExpressionStatement) + (Maybe JSExpression) + (Maybe JSExpressionStatement) + [JSStatement] | JSForStatementInStyle JSName JSExpression @@ -289,185 +360,267 @@ -- -- | Concrete syntax: --- do { * } while ( ); -- +-- @do { \* } while ( \ );@ +-- data JSDoStatement = JSDoStatement [JSStatement] JSExpression -- -- | Concrete syntax: --- while ( ) { * } -- +-- @while ( \) { \* }@ +-- data JSWhileStatement = JSWhileStatement JSExpression [JSStatement] -- -- | Concrete syntax: --- try { * } catch ( ) { * } -- +-- @try { \* } catch ( \ ) { \* }@ +-- data JSTryStatement = JSTryStatement [JSStatement] JSName [JSStatement] -- -- | Concrete syntax: --- throw ; -- +-- @throw \;@ +-- data JSThrowStatement = JSThrowStatement JSExpression -- -- | Concrete syntax: --- return ?; +-- +-- @return \?;@ +-- -- e.g. --- 1. return; --- 2. return 2 + x; -- +-- 1. @return;@ +-- +-- 2. @return 2 + x;@ +-- data JSReturnStatement = JSReturnStatement (Maybe JSExpression) -- -- | Concrete syntax: --- break ?; --- e.g. --- 1. break; --- 2. break some_label; -- +-- @break \?;@ +-- +-- e.g. +-- +-- 1. @break;@ +-- +-- 2. @break some_label;@ +-- data JSBreakStatement = JSBreakStatement (Maybe JSName) -- -- | Concrete syntax: -- +-- @\+ \@ -- - +-- or +-- +-- @delete \ \@ +-- data JSExpressionStatement = JSESApply (NonEmptyList JSLValue) JSRValue | JSESDelete JSExpression JSRefinement -- -- | Concrete syntax: --- \(* \)* +-- +-- @\ \(\* \\)*@ +-- -- e.g. --- 1. x --- 2. x.field_1 --- 3. fun().field_1 --- 4. fun(1)(2) --- 5. fun(1)(2).field_1 --- 5. x.fun_field_1(x+2).fun_field_2(y+3).field_3 -- +-- 1. @x@ +-- +-- 2. @x.field_1@ +-- +-- 3. @fun().field_1@ +-- +-- 4. @fun(1)(2)@ +-- +-- 5. @fun(1)(2).field_1@ +-- +-- 6. @x.fun_field_1(x+2).fun_field_2(y+3).field_3@ +-- data JSLValue = JSLValue JSName [([JSInvocation], JSRefinement)] -- -- | Concrete syntax: --- 1. = --- 2. += --- 3. -= --- 4. + -- --- e.g. --- 1. = 2 --- 2. += 3 --- 3. -= (4 + y) --- 4a. () --- 4b. (1) --- 4c. (x,y,z) +-- @= \@ -- +-- or +-- +-- @+= \@ +-- +-- or +-- +-- @-= \@ +-- +-- or +-- +-- @\+@ +-- +-- e.g. +-- +-- 1. @= 2@ +-- +-- 2. @+= 3@ +-- +-- 3. @-= (4 + y)@ +-- +-- 4. @()@ +-- +-- 5. @(1)@ +-- +-- 6. @(x,y,z)@ +-- data JSRValue = JSRVAssign JSExpression | JSRVAddAssign JSExpression | JSRVSubAssign JSExpression | JSRVInvoke (NonEmptyList JSInvocation) -data JSExpression = JSExpressionLiteral JSLiteral - | JSExpressionName JSName +data JSExpression = JSExpressionLiteral JSLiteral -- ^ @\@ + | JSExpressionName JSName -- ^ @\@ + + -- | @\ \@ | JSExpressionPrefix JSPrefixOperator JSExpression + + -- | @\ \ \@ | JSExpressionInfix JSInfixOperator JSExpression JSExpression + + -- | @\ ? \ : \@ | JSExpressionTernary JSExpression JSExpression JSExpression + + -- | @\\@ | JSExpressionInvocation JSExpression JSInvocation + + -- | @\\@ | JSExpressionRefinement JSExpression JSRefinement + + -- | new @\\@ | JSExpressionNew JSExpression JSInvocation + + -- | delete @\\@ | JSExpressionDelete JSExpression JSRefinement data JSPrefixOperator - = JSTypeOf -- syntax: typeof - | JSToNumber -- syntax: + - | JSNegate -- syntax: - - | JSNot -- syntax: ! + = JSTypeOf -- ^ @typeof@ + | JSToNumber -- ^ @+@ + | JSNegate -- ^ @-@ + | JSNot -- ^ @!@ data JSInfixOperator - = JSMul -- syntax: * - | JSDiv -- syntax: / - | JSMod -- syntax: % - | JSAdd -- syntax: + - | JSSub -- syntax: - - | JSGTE -- syntax: >= - | JSLTE -- syntax: <= - | JSGT -- syntax: > - | JSLT -- syntax: < - | JSEq -- syntax: === - | JSNotEq-- syntax: !== - | JSOr -- syntax: || - | JSAnd -- syntax: && + = JSMul -- ^ @*@ + | JSDiv -- ^ @/@ + | JSMod -- ^ @%@ + | JSAdd -- ^ @+@ + | JSSub -- ^ @-@ + | JSGTE -- ^ @>=@ + | JSLTE -- ^ @<=@ + | JSGT -- ^ @>@ + | JSLT -- ^ @<@ + | JSEq -- ^ @===@ + | JSNotEq-- ^ @!==@ + | JSOr -- ^ @||@ + | JSAnd -- ^ @&&@ -- -- | Concrete syntax: --- * +-- +-- @\*@ +-- -- e.g. --- 1. () --- 2. (1) --- 3. (x,z,y) -- +-- 1. @()@ +-- +-- 2. @(1)@ +-- +-- 3. @(x,z,y)@ +-- data JSInvocation = JSInvocation [JSExpression] --- e.g. --- 1. .field_1 --- 2. [i+1] +-- | Concrete syntax: -- +-- @.\@ +-- +-- or +-- +-- @[\]@ +-- +-- e.g. +-- +-- 1. @.field_1@ +-- +-- 2. @[i+1]@ +-- data JSRefinement - -- | syntax: . - -- e.g. .field_1 = JSProperty JSName - -- | syntax: [] - -- e.g. [x+3] | JSSubscript JSExpression data JSLiteral - = JSLiteralNumber JSNumber - | JSLiteralString JSString - | JSLiteralObject JSObjectLiteral - | JSLiteralArray JSArrayLiteral - | JSLiteralFunction JSFunctionLiteral + = JSLiteralNumber JSNumber -- ^ @\@ + | JSLiteralString JSString -- ^ @\@ + | JSLiteralObject JSObjectLiteral -- ^ @\@ + | JSLiteralArray JSArrayLiteral -- ^ @\@ + | JSLiteralFunction JSFunctionLiteral -- ^ @\@ -- | JSLiteralRegexp JSRegexpLiteral -- TODO: Add regexps -- -- | Concrete syntax: --- 1. {} // no fields --- 2. { \(, \)*} // one or more fields -- +-- @{}@ -- no fields +-- +-- or +-- +-- @\{\ \(, \ \)*\}@ -- one or more fields +-- data JSObjectLiteral = JSObjectLiteral [JSObjectField] -- -- | Concrete syntax: --- 1. : // for Left --- 2. : // for Right -- +-- @\: \ @ -- for Left +-- +-- or +-- +-- @\: \ @ -- for Right +-- -- e.g. --- 1. x: y + 3 --- 2. "value": 3 - z -- +-- 1. @x: y + 3@ +-- +-- 2. @\"value\": 3 - z@ +-- data JSObjectField = JSObjectField (Either JSName JSString) JSExpression -- -- | Concrete syntax: --- 1. [] // empty array --- 2. [ \(, *\) ] -- +-- @[]@ -- empty array +-- +-- or +-- +-- @[\ \(, \*\) ]@ -- non empty array +-- data JSArrayLiteral = JSArrayLiteral [JSExpression] -- -- | Concrete syntax: --- function ? -- +-- @function \? \@ +-- data JSFunctionLiteral = JSFunctionLiteral (Maybe JSName) [JSName] JSFunctionBody -- -- | Concrete syntax: --- { + + } -- +-- @{ \+ \+ }@ +-- data JSFunctionBody = JSFunctionBody [JSVarStatement] [JSStatement] +-- | Programs. All variable statements come first. data JSProgram = JSProgram [JSVarStatement] [JSStatement] diff --git a/src/Language/JavaScript/NonEmptyList.hs b/src/Language/JavaScript/NonEmptyList.hs new file mode 100644 --- /dev/null +++ b/src/Language/JavaScript/NonEmptyList.hs @@ -0,0 +1,30 @@ +-- +-- +-- Author: Sean Seefried +-- © 2012 +-- +-- Non-empty lists. +-- +module Language.JavaScript.NonEmptyList ( + NonEmptyList, + singleton, (<:>), + toList + +) where + +-- A list of at least one element +data NonEmptyList a = Singleton a | Cons a (NonEmptyList a) + +singleton :: a -> NonEmptyList a +singleton = Singleton + +(<:>) :: a -> NonEmptyList a -> NonEmptyList a +x <:> xs = Cons x xs + +instance Functor NonEmptyList where + fmap f (Singleton a) = Singleton (f a) + fmap f (Cons x xs) = Cons (f x) (fmap f xs) + +toList :: NonEmptyList a -> [a] +toList (Singleton a) = [a] +toList (Cons x xs) = x : toList xs diff --git a/src/Language/JavaScript/Pretty.hs b/src/Language/JavaScript/Pretty.hs --- a/src/Language/JavaScript/Pretty.hs +++ b/src/Language/JavaScript/Pretty.hs @@ -94,14 +94,6 @@ JSAnd -> go 2 "&&" where go i s = OpInfo i LeftToRight s -prefixOpInfo :: JSPrefixOperator -> OpInfo -prefixOpInfo op = case op of - JSTypeOf -> go 7 "typeof" - JSToNumber -> go 7 "+" - JSNegate -> go 7 "-" - JSNot -> go 7 "!" - where go i s = OpInfo i RightToLeft s - ----------------------------------------------------------------------- instance Pretty JSNumber where