{"action":"created","issue":{"url":"https://api.github.com/repos/Microsoft/TypeScript/issues/4691","labels_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/4691/labels{/name}","comments_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/4691/comments","events_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/4691/events","html_url":"https://github.com/Microsoft/TypeScript/issues/4691","id":105411046,"number":4691,"title":"Proposal: Preprocessor Directives","user":{"login":"yortus","id":1252361,"avatar_url":"https://avatars.githubusercontent.com/u/1252361?v=3","gravatar_id":"","url":"https://api.github.com/users/yortus","html_url":"https://github.com/yortus","followers_url":"https://api.github.com/users/yortus/followers","following_url":"https://api.github.com/users/yortus/following{/other_user}","gists_url":"https://api.github.com/users/yortus/gists{/gist_id}","starred_url":"https://api.github.com/users/yortus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yortus/subscriptions","organizations_url":"https://api.github.com/users/yortus/orgs","repos_url":"https://api.github.com/users/yortus/repos","events_url":"https://api.github.com/users/yortus/events{/privacy}","received_events_url":"https://api.github.com/users/yortus/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2015-09-08T15:54:01Z","updated_at":"2015-09-09T03:18:29Z","closed_at":null,"body":"This proposal is based on a working implementation at:\r\nhttps://github.com/yortus/TypeScript/tree/preprocessor-directives\r\n\r\n## Problem Scenario\r\n\r\nWhilst the TypeScript compiler has some options to control what to *emit* for a particular source file, it currently has limited support for controlling what is *scanned* into the compiler from a particular source file. A source file is either included in its entirety, or not at all.\r\n\r\nThis makes some scenarios difficult. For instance, there are two default lib files, `lib.d.ts`, and `lib.es6.d.ts`. A program may be compiled against one, or the other, or neither. If only *some* ES6 typings are desired, then either they must *all* be taken (using `lib.es6.d.ts`), or a custom set of core typings must be maintained with the project.\r\n\r\nEven if the core lib files were further subdivided into smaller modular files that could be selectively included in a build, problems would remain. For instance, consider an ES6 built-in, `WeakMap`, which has members that use the ES6 `Symbol` spec and the ES6 `Iterable` spec. How many files must the `WeakMap` definition be broken into to keep the lib files feature-modular?\r\n\r\nRelated scenarios have been discussed in other issues:\r\n* (#4671) Conditional compilation\r\n* (#3670) Preprocessor directives proposal\r\n* (#3538) Proposal: Conditional Compilation\r\n* (#449) Support conditional compilation\r\n\r\nThis proposal focuses on the `lib.d.ts` modularity problem, since that was the core requirement for the related proposal (#4692) that motivated the [working implementation](https://github.com/yortus/TypeScript/tree/preprocessor-directives).\r\n\r\n## Workarounds\r\n\r\nWith regards to compiling core typings for *only some* ES6 features, some workarounds are:\r\n* compile with `--target ES5` and selectively add ES6 typings in separately maintained files (eg from DefinitelyTyped).\r\n* compile with `--target ES6` and be careful to avoid referencing unsupported ES6 features (the compiler won't issue any errors).\r\n* compile with `--noLib` and manually maintain custom core typings in your own project.\r\n\r\nFor other scenarios, such as supporting `DEBUG` builds or `IOS` builds etc, a common practice is to use a single codebase with conditional execution to differentiate behaviour in different environments. This generally works well, except if conditional `require(...)`s are needed, as these can be a problem for some module systems that statically analyse module dependencies.\r\n\r\n## Proposed Solution\r\n\r\nThis proposal adds a new kind of syntax for *preprocessor directives*.\r\n\r\n### Preprocessor Directive Syntax\r\nA preprocesor directive:\r\n\r\n* begins with a '#' followed by the directive identifier, eg `#if`, `#endif`\r\n* *must* be the first non-whitespace element on its line\r\n* *must not* be followed on the same line by anything other than whitespace and/or a single-line comment\r\n\r\n**Valid:**\r\n```\r\n    #if DEBUG\r\n#endif // end of debug section\r\n\r\n```\r\n**Invalid:**\r\n```\r\n}  #if DEBUG\r\n#if X  foo(); #endif \r\n\r\n```\r\n\r\n\r\n### Directives with Arguments\r\nA preprocessor directive may take an argument. If so, the argument appears after the directive identifier on the same line. The directive identifier and its argument must be separated by at least one whitespace character.\r\n\r\nUnder this proposal, only `#if` takes an argument, which must be an identifier. An extended proposal may expand argument syntax to include preprocessor symbol expressions.\r\n\r\n### Contextual Interpretation\r\nIf a syntactically valid preprocessor directive appears inside a multiline comment or a multiline string, it is not considered a preprocessor directive. It remains a normal part of the enclosing comment or string.\r\n```\r\n/*\r\n   The next line is NOT a preprocessor directive\r\n   #if XYZ\r\n*/\r\n```\r\n\r\n### Preprocessor Symbols\r\nA preprocessor symbol is an identifier used with some directives (only `#if` under this proposal). Preprocessor symbols have no values, they are simply *defined* or *undefined*. Under this proposal, the only way to define a preprocessor symbol is using the `define` compiler option (see below).\r\n\r\nPreprocessor symbols are in a completely separate space to all other identifiers in source code; they may have the same names as source code identifiers, but they never clash with them.\r\n```\r\n#if DEBUG\r\n#if SomeFeature\r\n#if __condition\r\n#if TARGET_HAS_ITERABLES\r\n```\r\n\r\n### `#if` and `#endif`\r\nThe `#if` and `#endif` preprocessor directives signal the start and end of a block of conditionally compiled source code. `#if` must be given a *preprocessor symbol* as an argument. `#endif` takes no argument. Each `#if` in a file must have a matching `#endif` on a subsequent line in that file.\r\n\r\nWhen the TypeScript compiler encounters an `#if` directive, it evaluates its preprocessor symbol against a list of defined symbols. If the symbol is defined, then the TypeScript scanner continues scanning the source file normally, as if the directive was not present. If the symbol is *not* defined, then the compiler skips all the source code down to the matching `#endif` without compiling it.\r\n\r\n`#if...#endif` blocks may be nested. Inner blocks will be unconditionally skipped if their outer block is being skipped.\r\n\r\n```\r\n#if HAS_FOO\r\nfoo();\r\n#endif\r\n\r\n#if HAS_FOO\r\nfoo();\r\n#if HAS_BAR\r\nfoo() + bar();\r\n#endif\r\n#endif\r\n```\r\n\r\n\r\n### The `define` Compiler Option\r\nPreprocessor symbols may be defined at compile time using the `define` compiler option, which takes a comma-separated list of identifiers.\r\n\r\n```\r\ntsc --define FOO,bar\r\n\r\n{\r\n    \"target\": \"es6\",\r\n    \"define\": \"DEBUG,__foo,ABC\"\r\n}\r\n```\r\n \r\n### Possible Extensions\r\nThis proposal is limited to a small set of features that are useful on their own, but may be expanded.\r\n\r\nIn particular, `#if` and `#endif` alone are sufficient to address the `lib.d.ts` problem described above, as evidenced in the [working implementation](https://github.com/yortus/TypeScript/tree/granular-targeting) of #4692. The ability to nest `#if...#endif` blocks effectively allows logical ANDing of preprocesor symbols.\r\n\r\nPossible extensions include:\r\n* `#define` and `#undef` directives to add/remove preprocessor symbols from within source code. However the question of symbol scope then arises.\r\n* Unary and binary expressions involving preprocessor symbols, such as `!` (logical NOT), `&&` logical AND, and `||` logical OR.\r\n\r\n## Backward Compatibility, Design Impact, Performance, etc\r\n* There is no impact on existing TypeScript projects. The preprocessor directives only modify the compiler's behaviour if they are explicitly used.\r\n* Preprocessor directives introduce new language syntax, but do not affect any existing language features.\r\n* There is negligable impact on compiler performance.\r\n* The hash symbol is only used in shebang trivia at present. There is no syntax clash. But could it be used for something in a future ES standard?\r\n\r\n## Remaining Work and Questions\r\nThe [working implementation](https://github.com/yortus/TypeScript/tree/preprocessor-directives) implements preprocessor directives in the TypeScript scanner, since they are really a filter on incoming tokens. This works fairly well for this limited proposal, but questions arise if extensions were added:\r\n* if `#define/#undef` were added, how should preprocessor symbols be scoped? Global? Per file? The scanner has very limited control over scoping. Hence currently preprocessor symbols are all globally scoped and provided using a compiler option (or internally generated by the compiler).\r\n* Supporting expressions as preprocessor arguments would add complexity to the scanner, as it would need to parse a mini grammar for the expression, which would be atypical at the lexer stage. But certainly doable.\r\n"},"comment":{"url":"https://api.github.com/repos/Microsoft/TypeScript/issues/comments/138765131","html_url":"https://github.com/Microsoft/TypeScript/issues/4691#issuecomment-138765131","issue_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/4691","id":138765131,"user":{"login":"yortus","id":1252361,"avatar_url":"https://avatars.githubusercontent.com/u/1252361?v=3","gravatar_id":"","url":"https://api.github.com/users/yortus","html_url":"https://github.com/yortus","followers_url":"https://api.github.com/users/yortus/followers","following_url":"https://api.github.com/users/yortus/following{/other_user}","gists_url":"https://api.github.com/users/yortus/gists{/gist_id}","starred_url":"https://api.github.com/users/yortus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yortus/subscriptions","organizations_url":"https://api.github.com/users/yortus/orgs","repos_url":"https://api.github.com/users/yortus/repos","events_url":"https://api.github.com/users/yortus/events{/privacy}","received_events_url":"https://api.github.com/users/yortus/received_events","type":"User","site_admin":false},"created_at":"2015-09-09T03:18:29Z","updated_at":"2015-09-09T03:18:29Z","body":"@weswigham to add to my above comment, as long as are other solutions can be found to 'selectively choosing parts of lib.d.ts files', that don't require adding a proprocessor to tsc, I agree that preprocessor directives are unlikely to have other compelling use cases."}}