preprod

a custom old-school preprocessor for nim

MOTIVATION

"If you want more effective programmers, you will discover that they should not waste their time debugging, they should not introduce the bugs to starth with."

Edger Dijkstra, The Humble Programmer, 1972

CHARACTERISTICS

16 builtin commands separated into 5 different groups (called features)
independient feature set enablement
custom defines and branching logic support
external file inclusions
deferred command execution support
comments support
custom callbacks for preview and translate passes
overridable error formatter
and more

BUILTIN COMMANDS

STANDARD feature

FEATURE command: enables/disables a feature (command group)
NOOP command: no operation
STOP command: stops execution with a custom message
DEFER command: defers the execution of the command specified

INCLUDES feature

INCLUDE command: includes an external file into the preprocessed contents

COMMENTS feature

COMMENT command: customizes the character used to comment ('#' by default)

CONSOLES feature

INFO command: emit text to stdout when previewing
DEBUG command: emits text to stderr when previewing
PRINT command: emit text to stdout when translating
ERROR command: emit text to stderr when translating

BRANCHES feature

IFDEF command: open a branch if something is defined
IFNDEF command: open a branch if something is not defined
ELSE command: toggles the branch
ENDIF command: ends the branch
DEF command: adds a conditional define
UNDEF command: deletes a conditional define

AVAILABLE OPTIONS

allowLeftWhitespace: enables/disables the acceptance of whitespace before a command (true by default)

linePrefix: customizes the line prefix (".$" by default)

initialCommentPrefix: sets the initial comment prefix ("#" by default)

initialEnabledFeatures: customizes the initial enabled features (all by default)

initialConditionalDefines: sets the initial conditional defines (none by default)

customPrefix: sets the prefix for custom commands ("." by default)

keepBlankLines: establishes if produced blank lines are kept in the output (true by default)

initialLineAppendix: sets the initial line appendix (EOL by default)

USAGE

    var opt = newPreprodOptions()
    opt.initialConditionalDefines = @["x"]
    let p = newPreprodPreprocessor(@[
      ".$ IFDEF x",
      "x!",
      ".$ ELSE",
      "no x!",
      ".$ ENDIF"
    ], opt)
    let r = p.run()
    if r.ok:
      echo r.output # "x!"

You may also want to check my other nimlang projects:

xam, my multipurpose productivity library for nim
rodster, my application framework for nim
webrod, my http server for nim

HISTORY

13-05-22 [1.1.1]
- added newPreprodOptions to exports
- general improvements
12-05-22 [1.1.0]
- added overridable error formatter to allow message customization
- added PreprodFormatter, PreprodError and PREPROD_ERROR_FORMATS to exports
- updated xam dependency to 1.8.0
09-02-22 [1.0.2]
- added registerFeature, hasFeature, enableFeature and isFeatureEnabled to exports
- added constructors overloads
08-02-22 [1.0.1]
- added hasConditionalDefine, addConditionalDefine, removeConditionalDefine to exports
- updated xam dependency to 1.7.0
28-12-21 [1.0.0]
- first public release
08-12-21 [0.0.1]
- started coding

j-a-s-d/preprod