15.3.335  src/lib/make-library-glue/patchfile.api

## patchfile.api
#
# Adding content to files in spots
# marked by linepairs like
#
#    # Do not edit this or following lines --- they are autobuilt.  (patchname="foo")
#    ...
#    # Do not edit this or preceding lines --- they are autobuilt.  (patchname="foo")
#
# NB: It is expected that most application programmers
#     will primarily use the Patchfiles api from
#
#     src/lib/make-library-glue/patchfiles.api

# Compiled by:
#     src/lib/std/standard.lib


stipulate
    package sm  =  string_map;                                                                                  # string_map            is from   src/lib/src/string-map.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/make-library-glue/patchfile.pkg
    #
    api  Patchfile
    {
        Patch = {       patchname:      String,                                                                 # patchname will be "functions" for a patch started by:
                        lines:          List(String)                                                            #     # Do not edit this or following lines --- they are autobuilt.  (patchname="functions")
                };

        Patch_Id  =   { filename:       String,
                        patchname:      String
                      };

        Patch'    =   { patch_id:       Patch_Id,
                        lines:          List(String)
                      };

        Patchfile;

        get_patch_names:        Patchfile -> List(String);

        get_patch:              (Patchfile, String) -> Patch;                                                   # Get patch by name.

        print_patchfile:        Patchfile -> Void;

        read_patchfile:         String -> Patchfile;

        write_patchfile:        Patchfile                -> String;
        write_patchfile':       Patchfile -> List(Patch) -> String;

        patch_count:            Patchfile -> Int;
        text_count:             Patchfile -> Int;

        get_only_patch:         Patchfile -> List(String);                                                      # Patchfile must contain exactly one patch.
        set_only_patch:         Patchfile -> List(String) -> Patchfile;                                         # Patchfile must contain exactly one patch.

        apply_patch:            Patchfile ->      Patch  -> Patchfile;                                          # 
        apply_patches:          Patchfile -> List(Patch) -> Patchfile;                                          # 

        append_to_patch:        (Patchfile, String, List(String)) -> Patchfile;                                 # Append  given lines to named patch.
        prepend_to_patch:       (Patchfile, String, List(String)) -> Patchfile;                                 # Prepend given lines to named patch.

        empty_all_patches:      Patchfile -> Patchfile;                                                         # Set every patch to contain the empty list.

        make_patch_beginline:   { patchname: String } -> String;
        make_patch_endline:     { patchname: String } -> String;
            #
            # These return respectively 
            #     " Do not edit this or following lines --- they are autobuilt.  (patchname="<patchname>")"
            #     " Do not edit this or preceding lines --- they are autobuilt.  (patchname="<patchname>")"
            # Use them to avoid embedding knowledge of these magic strings in client files.


        map:                    (Patch' -> List(String)) -> Patchfile -> Patchfile;                             # Set contents of each patch to some function of that patch.                                                    
        apply:                  (Patch' -> Void)         -> Patchfile -> Void;                                  # Call user_fn on every patch in file.
        fold:                   ((Patch', Y) -> Y)  -> Y -> Patchfile -> Y;                                     # Compute some statistic over all patches.
    };
end;