gdritter repos config-ini / 13b048e
More doc edits for bidir Getty Ritter 6 years ago
1 changed file(s) with 31 addition(s) and 17 deletion(s). Collapse all Expand all
+31
-17
src/Data/Ini/Config/Bidir.hs less more
568568 _2 = lens snd (\ b (a, _) -> (a, b))
569569
570570
571 {- | $main
572 This module is an alternate API used for parsing INI files.
573 unlike the standard API, it is bidirectional: it can be also used
574 to emit an INI, or even to produce an updated INI file with minimal
575 modification to the textual file provided.
571
572 {- $main This module is an alternate API used for parsing INI files.
573 Unlike the standard API, it is bidirectional: the same declarative
574 structure can be also used to emit an INI file, or even to produce an
575 updated INI file with minimal modification to the textual file
576 provided.
576577
577578 This module makes some extra assumptions about your configuration type
578579 and the way you interact with it: in particular, it assumes that you
579580 have lenses for all the fields you're parsing, and that you have some
580581 kind of sensible default value of that configuration. Instead of
581582 providing combinators which can extract and parse a field of an INI
582 file into a value, the bidirectional API has you declaratively
583 associate lenses into your structure with descriptions of their
584 corresponding fields in INI files.
583 file into a value, the bidirectional API allows you to declaratively
584 map lenses into your structure to descriptions of corresponding fields
585 in INI files.
585586
586587 Consider the following example INI file:
587588
593594 > user = terry
594595
595596 We'd like to parse this INI file into a @Config@ type which we've
596 defined like this, using whatever "lens"-like library we prefer:
597 defined like this, using "lens" or a similar library to provide
598 lenses:
597599
598600 > data Config = Config
599601 > { _cfHost :: String
603605 >
604606 > ''makeLenses Config
605607
606 We define a basic specification of type @IniSpec Config ()@ by using
607 the provided combinators to declare sections and then associate fields
608 in those sections with lenses into our @Config@ structure.
608 We can now define a basic specification of the type @IniSpec Config
609 ()@ by using the provided operations to declare our top-level
610 sections, and then within those sections associate fields with lenses
611 into our @Config@ structure.
609612
610613 > configSpec :: IniSpec Config ()
611614 > configSpec = do
621624 configuration. Each 'field' invocation must include the name of the
622625 field and a representation of the type of that field: 'string',
623626 'number', and 'text' in the above snippet are all values of type
624 'FieldValue', which bundles together a parser and serializer for a
625 value.
627 'FieldValue', which bundle together a parser and serializer so that
628 they can be used bidirectionally.
626629
627630 We can also provide extra metadata about a field, allowing it to be
628631 skipped in parsing, or to provide an explicit default value, or to
634637 > configSpec = do
635638 > section "NETWORK" $ do
636639 > cfHost .= field "host" string
637 > & comment ["A comment about the host"]
640 > & comment ["The desired hostname (optional)"]
641 > & skipIfMissing
638642 > cfPost .= field "port" number
643 > & comment ["The port number"]
639644 > & defaultValue 9999
640645 > section "LOCAL" $ do
641646 > cfUser .=? field "user" text
642647
643648 In order to parse an INI file, we need to provide a default value of
644 our underlying @config@ type on which we can perform our 'Lens'-based
645 updates.
649 our underlying @Config@ type on which we can perform our 'Lens'-based
650 updates. Parsing will then walk the specification and update each
651 field in the default value to the field provided in the INI file. We
652 can also use a value of our @Config@ type and serialize it directly,
653 which is useful for generating a default configuration: this will
654 include the comments we've provided and (optionally) commented-out
655 key-value pairs representing default values. Finally, we can /update/
656 a configuration file, reflecting changes to a value back to an
657 existing INI file in a way that preserves incidental structure like
658 spacing and comments.
659
646660 -}