github.com/dop251/goja@v0.0.0-20240220182346-e401ed450204/parser/README.markdown (about)

     1  # parser
     2  --
     3      import "github.com/dop251/goja/parser"
     4  
     5  Package parser implements a parser for JavaScript. Borrowed from https://github.com/robertkrimen/otto/tree/master/parser
     6  
     7      import (
     8          "github.com/dop251/goja/parser"
     9      )
    10  
    11  Parse and return an AST
    12  
    13      filename := "" // A filename is optional
    14      src := `
    15          // Sample xyzzy example
    16          (function(){
    17              if (3.14159 > 0) {
    18                  console.log("Hello, World.");
    19                  return;
    20              }
    21  
    22              var xyzzy = NaN;
    23              console.log("Nothing happens.");
    24              return xyzzy;
    25          })();
    26      `
    27  
    28      // Parse some JavaScript, yielding a *ast.Program and/or an ErrorList
    29      program, err := parser.ParseFile(nil, filename, src, 0)
    30  
    31  
    32  ### Warning
    33  
    34  The parser and AST interfaces are still works-in-progress (particularly where
    35  node types are concerned) and may change in the future.
    36  
    37  ## Usage
    38  
    39  #### func  ParseFile
    40  
    41  ```go
    42  func ParseFile(fileSet *file.FileSet, filename string, src interface{}, mode Mode) (*ast.Program, error)
    43  ```
    44  ParseFile parses the source code of a single JavaScript/ECMAScript source file
    45  and returns the corresponding ast.Program node.
    46  
    47  If fileSet == nil, ParseFile parses source without a FileSet. If fileSet != nil,
    48  ParseFile first adds filename and src to fileSet.
    49  
    50  The filename argument is optional and is used for labelling errors, etc.
    51  
    52  src may be a string, a byte slice, a bytes.Buffer, or an io.Reader, but it MUST
    53  always be in UTF-8.
    54  
    55      // Parse some JavaScript, yielding a *ast.Program and/or an ErrorList
    56      program, err := parser.ParseFile(nil, "", `if (abc > 1) {}`, 0)
    57  
    58  #### func  ParseFunction
    59  
    60  ```go
    61  func ParseFunction(parameterList, body string) (*ast.FunctionLiteral, error)
    62  ```
    63  ParseFunction parses a given parameter list and body as a function and returns
    64  the corresponding ast.FunctionLiteral node.
    65  
    66  The parameter list, if any, should be a comma-separated list of identifiers.
    67  
    68  #### func  ReadSource
    69  
    70  ```go
    71  func ReadSource(filename string, src interface{}) ([]byte, error)
    72  ```
    73  
    74  #### func  TransformRegExp
    75  
    76  ```go
    77  func TransformRegExp(pattern string) (string, error)
    78  ```
    79  TransformRegExp transforms a JavaScript pattern into a Go "regexp" pattern.
    80  
    81  re2 (Go) cannot do backtracking, so the presence of a lookahead (?=) (?!) or
    82  backreference (\1, \2, ...) will cause an error.
    83  
    84  re2 (Go) has a different definition for \s: [\t\n\f\r ]. The JavaScript
    85  definition, on the other hand, also includes \v, Unicode "Separator, Space",
    86  etc.
    87  
    88  If the pattern is invalid (not valid even in JavaScript), then this function
    89  returns the empty string and an error.
    90  
    91  If the pattern is valid, but incompatible (contains a lookahead or
    92  backreference), then this function returns the transformation (a non-empty
    93  string) AND an error.
    94  
    95  #### type Error
    96  
    97  ```go
    98  type Error struct {
    99  	Position file.Position
   100  	Message  string
   101  }
   102  ```
   103  
   104  An Error represents a parsing error. It includes the position where the error
   105  occurred and a message/description.
   106  
   107  #### func (Error) Error
   108  
   109  ```go
   110  func (self Error) Error() string
   111  ```
   112  
   113  #### type ErrorList
   114  
   115  ```go
   116  type ErrorList []*Error
   117  ```
   118  
   119  ErrorList is a list of *Errors.
   120  
   121  #### func (*ErrorList) Add
   122  
   123  ```go
   124  func (self *ErrorList) Add(position file.Position, msg string)
   125  ```
   126  Add adds an Error with given position and message to an ErrorList.
   127  
   128  #### func (ErrorList) Err
   129  
   130  ```go
   131  func (self ErrorList) Err() error
   132  ```
   133  Err returns an error equivalent to this ErrorList. If the list is empty, Err
   134  returns nil.
   135  
   136  #### func (ErrorList) Error
   137  
   138  ```go
   139  func (self ErrorList) Error() string
   140  ```
   141  Error implements the Error interface.
   142  
   143  #### func (ErrorList) Len
   144  
   145  ```go
   146  func (self ErrorList) Len() int
   147  ```
   148  
   149  #### func (ErrorList) Less
   150  
   151  ```go
   152  func (self ErrorList) Less(i, j int) bool
   153  ```
   154  
   155  #### func (*ErrorList) Reset
   156  
   157  ```go
   158  func (self *ErrorList) Reset()
   159  ```
   160  Reset resets an ErrorList to no errors.
   161  
   162  #### func (ErrorList) Sort
   163  
   164  ```go
   165  func (self ErrorList) Sort()
   166  ```
   167  
   168  #### func (ErrorList) Swap
   169  
   170  ```go
   171  func (self ErrorList) Swap(i, j int)
   172  ```
   173  
   174  #### type Mode
   175  
   176  ```go
   177  type Mode uint
   178  ```
   179  
   180  A Mode value is a set of flags (or 0). They control optional parser
   181  functionality.
   182  
   183  --
   184  **godocdown** http://github.com/robertkrimen/godocdown