Foreign.Hoppy.Generator.Main

A driver for a command-line interface to a generator.

A simple Main.hs for a generator can simply be:

import Foreign.Hoppy.Generator.Main (defaultMain)
import Foreign.Hoppy.Generator.Spec (ErrorMsg, Interface, interface)

interfaceResult :: Either ErrorMsg Interface
interfaceResult = interface ...

main :: IO ()
main = defaultMain interfaceResult

Documentation

data Action

Actions that can be requested of the program.

Constructors

SelectInterface String

Sets the interface that will be used for subsequent actions.

ListInterfaces

Lists the interfaces compiled into the generator.

ListCppFiles

Lists the generated files in C++ bindings.

ListHsFiles

Lists the generated files in Haskell bindings.

GenCpp FilePath

Generates C++ wrappers for an interface in the given location.

GenHaskell FilePath

Generates Haskell bindings for an interface in the given location.

CleanCpp FilePath

Removes the generated files in C++ bindings.

KeepTempOutputsOnFailure

Instructs the generator to keep on disk any temporary programs or files created, in case of failure.

DumpExtNames

Dumps to stdout information about all external names in the current interface.

DumpEnums

Dumps to stdout information about all enums in the current interface.

EnumEvalCachePath (Maybe FilePath)

Specifies the path to a enum evaluation cache file to use.

EnumEvalCacheMode EnumEvalCacheMode

Specifies the behaviour with respect to how the enum evaluation cache cache file is used.

data EnumEvalCacheMode

Controls the behaviour of a generatior with respect to the enum cache file, when a file path provided (--enum-eval-cache-path).

If enum evaluation is required, based on the presence of the cache file and which of these modes is selected, then the compiler will be called and the results will be written to the cache file

If an enum cache file path is not provided, then this mode is ignored, and enum evaluation is attempted if a generator requires it.

Change detection is not currently supported. There is no ability to detect whether the cache file is up to date and contains all of the enum entries for the current state of the enums defined in an interface. The cache file is meant to be refreshed with RefreshEnumCache when building the C++ binding package, and installed with them so that the Haskell binding package can use EnumCacheMustExist.

Constructors

RefreshEnumCache

The default. Ignore the presence of an existing cache file, and evaluate enums freshly, updating the cache file with new contents.

EnumCacheMustExist

Require the cache file to exist. If it does not, enum evaluation will not be attempted; the generator will exit unsuccessfully instead.

defaultMain :: Either String Interface -> IO ()

This provides a simple main function for a generator. Define your main as:

main = defaultMain $ interface ...

Refer to run for how to use the command-line interface. Use defaultMain' if you want to include multiple interfaces in your generator.

defaultMain' :: [Either String Interface] -> IO ()

This is a version of defaultMain that accepts multiple interfaces.

ensureInterfaces :: [Either String Interface] -> IO [Interface]

Ensures that all of the entries in a list of results coming from interface are successful, and returns the list of Interface values. If any results are unsuccessful, then an error message is printed, and the program exits with an error (exitFailure).

run :: [Interface] -> [String] -> IO [Action]

run interfaces args runs the driver with the command-line arguments from args against the listed interfaces, and returns the list of actions performed.

The recognized arguments are listed below. The exact forms shown are required; the --long-arg=value style is not supported.

Arguments are processed in the order given, this means that settings must come before action arguments.

• --help: Displays a menu listing the valid commands.
• --list-interfaces: Lists the interfaces compiled into the generator.
• --interface <iface>: Sets the interface that will be used for subsequent arguments.
• --gen-cpp <outdir>: Generates C++ bindings in the given directory.
• --gen-hs <outdir>: Generates Haskell bindings under the given top-level source directory.
• --enum-eval-cache-path <cachefile>: Specifies a cache file to use for the results of enum evaluation. If the cache file already exists, then it may be loaded to save calling the compiler, depending on the cache mode (--enum-eval-cache-mode). Because enum evaluation results are required when generating both the C++ and Haskell interfaces and these are normally separate packages, this allows the C++ package's evaluation work to be shared with the Haskell package.
• --enum-eval-cache-mode <refresh|must-exist>: Controls the specific behaviour of the generator with respect to the enum evaluation cache file. See Action.