GYP File Format Parser

Common errors

• SyntaxError: Unexpected token '...' in GYP file

  cause The input GYP string contains a syntax error (e.g., unclosed quotes, incorrect punctuation, unsupported construct) that prevents successful parsing.
  fix Carefully review the GYP input string for any syntax inconsistencies. Ensure all strings are correctly quoted, dictionaries and arrays are properly terminated, and no invalid characters are present according to GYP rules.

• TypeError: parse is not a function

  cause This typically occurs in CommonJS environments if `require('gyp-parser')` is assigned directly to `parse` without destructuring, or if there's an attempt to call a default export that doesn't exist.
  fix For CommonJS, use `const { parse } = require('gyp-parser');`. In ESM, ensure you are using `import { parse } from 'gyp-parser';`.

• TypeError: Cannot read properties of undefined (reading 'some_key')

  cause Attempting to access a property on the parsed GYP object that does not exist or is undefined in the GYP structure.
  fix Verify the GYP file content and the property path you are trying to access. Add checks (e.g., `if (parsedData && parsedData.some_key)`) to handle cases where properties might be missing or optional.

Warnings

• gotcha Directly using `eval()` to parse GYP file content is strongly discouraged and can lead to incorrect parsing, security vulnerabilities, and runtime errors.
  Fix: Always use `gyp-parser`'s `parse` function. It is specifically designed to handle GYP syntax securely and correctly, including features like implicit string concatenation and dictionary merging that `eval()` will not support natively.
• gotcha This package is a parser only; it does not perform any I/O operations (e.g., reading files from disk).
  Fix: You must provide the GYP file content as a string to the `parse` function. Handle file reading (e.g., using `fs.readFileSync` in Node.js) separately before passing the content to `gyp-parser`.
• gotcha GYP syntax, while similar to JSON, has specific differences (e.g., unquoted keys, comments, string concatenation, variable expansion). Input must conform to GYP syntax, not strict JSON.
  Fix: Ensure the input string adheres to the GYP format. Errors for malformed GYP will be thrown as `SyntaxError` by the parser. Consult GYP documentation for exact syntax rules if encountering parsing issues.

Install

• npm install gyp-parser npm
• yarn add gyp-parser yarn
• pnpm add gyp-parser pnpm

Imports

• parse
  wrong:

  const parse = require('gyp-parser');

  correct:

  import { parse } from 'gyp-parser';

  The package is primarily designed for ESM environments and ships TypeScript types. While a CommonJS `require` might work with transpilation, direct named ESM import is the idiomatic way.
• parse (CommonJS)
  wrong:

  const parse = require('gyp-parser'); // This tries to import the default export, which doesn't exist for 'parse'

  correct:

  const { parse } = require('gyp-parser');

  For CommonJS environments, ensure you destructure the named export. However, native ESM usage is recommended.

Quickstart

This quickstart demonstrates parsing a complex GYP file string, including nested objects, arrays, variables, and actions, and then logging the resulting JavaScript object.

import { parse } from 'gyp-parser';

// Example GYP source with implicit string concatenation and a variable
const gypFileSource = `
  {
    'target_name': 'my_app',
    'type': 'executable',
    'variables': {
      'common_flags': [ '-Wall', '-std=c++17' ]
    },
    'sources': [
      'src/main.cc',
      'src/utils.cc'
    ],
    'defines': [
      'VERSION=1.0',
      'DEBUG=1'
    ],
    'configurations': {
      'Release': {
        'defines': [ 'NDEBUG=1' ]
      }
    },
    'actions': [
      {
        'action_name': 'generate_header',
        'inputs': [ 'templates/config.h.in' ],
        'outputs': [ '$$(RULE_DIR)/config.h' ],
        'action': ['python', 'generate_config.py', '<@(_inputs)', '>', '<@(_outputs)'],
      }
    ]
  }
`;

try {
  const parsedGyp = parse(gypFileSource);
  console.log('Successfully parsed GYP data:');
  console.log(JSON.stringify(parsedGyp, null, 2));

  // Accessing a specific property
  console.log(`\nTarget Name: ${parsedGyp.target_name}`);
  console.log(`Common Flags: ${parsedGyp.variables.common_flags.join(', ')}`);
} catch (error) {
  console.error('Failed to parse GYP data:', error.message);
}