UseFunc Header (Macro-Functions Wrapper) Readme
===============================================

UseFunc Header is a wrapper over macro-functions for the creation
of even easier headers for NSIS which have more features for users
besides of the easy inclusion and calling of functions.

1. How to use the UseFunc header
--------------------------------

  1.1 For Developers
  ------------------

    1.1.1 Creating new headers
    --------------------------

      1.1.1.1 The ${_UseFunc_DefHeader} macro
      ---------------------------------------

        The first thing to be in a header file is this macro.
        This defines the header name used by functions when
        they are created.

        Syntax:
        ${_UseFunc_DefHeader} Name VerMax VerMin VerBet VerAlp

        Name

          Specifies the name of the header, which can be used to
          retrive a list of functions, the version and etc.

          Also, this specifies the name of the header used by the functions
          that come after it. This name will appear as a part of the
          full function name, exactly at the left of the partial function
          name given to ${_UseFunc_DefFunc}. Example:

            "Str" header name + "Case" partial function name = "StrCase"
            function

          This macro also creates a define with the value given here
          called ${_HeaderName}.

        VerMax VerMin VerBet VerAlp

          Those four parameters consist the values for the version value
          for the header.

        1.2.1.1.1 Alternative ${_UseFunc_DefHeader_DifName} macro
        ---------------------------------------------------------

          Same as ${_UseFunc_DefHeader} except that it has an extra
          parameter to "fake" the name of the header.

          Syntax:
          ${_UseFunc_DefHeader_DifName} FakeName Name VerMax VerMin
          VerBet VerAlp

          FakeName
            
            This parameter is the same as the "Name" parameter,
            except that this is not considered the name of the
            header.

      1.1.1.2 The ${_UseFunc_DefFunc} macro
      -------------------------------------

      To create a function, this macro is necessary to
      identify the function and function call that come
      after this macro.

      Syntax:
      ${_UseFunc_DefFunc} Name VerMax VerMin VerBet VerAlp

      Name

        Specifies the name of the function, which can be used to
        retrive a list of functions, the version and etc.

        This macro also creates a define with the value given here
        called ${_Name}.

      VerMax VerMin VerBet VerAlp

        Those four parameters consist the values for the version value
        for the function.

        This macro also creates defines with the value given here
        called ${_Ver}.

        1.1.1.2.1 Alternative ${_UseFunc_DefFunc_NoFunc} macro
        ------------------------------------------------------

          Same as ${_UseFunc_DefHeader} except that it links the
          definition of the function directly to its function
          call function. This makes the function call
          function to turn into a normal function. Not recommended
          becasue you can't customize how the call is handled
          separatedly from the function code itself.

          If you use this, you should skip step 1.3.

          Syntax:
          ${_UseFunc_DefFunc_NoFunc} Name VerMax VerMin VerBet VerAlp

      1.1.1.3 Create a macro called ${_Func}
      --------------------------------------

        Now it's the function implementation step. This macro will
        create a function based on the full function name. This just
        names the macro though.

        To initialize the basic function procedures, the instruction
        ${_UseFunc_Func_Start} must be used at the start of this macro.
        Those basic procedures include assigning a defined
        verbosity to the code so it won't be seen by the user, and
        assigning a new link for the function define used by the user
        to the function call function.

        Now, you're free to put the code of your function there,
        excluding it's starting "Function" and ending "FunctionEnd"
        instructions, which are added to the start and end macros
        of the function.

        After that's done, you are required to put the ending
        ${_UseFunc_Func_End} instruction. This is just to make the
        verbosity of the function to the normal level.

      1.1.1.4 Create a macro called ${_FuncCall}
      ------------------------------------------

        Now it's the function call function implementation step.
        This macro will create a function based on the full function
        name. This just names the macro though.

        To initialize the basic function call function procedures, the
        instruction ${_UseFunc_FuncCall_Start} must be used at the
        start of this macro. A basic procedure is to assign
        a defined verbosity to the code so it won't be seen by the user.

        After that's done, you're free to put the code of your
        function call there, excluding it's starting "Function" and
        ending "FunctionEnd" instructions, which are added to the start
        and end macros of the function.

        It's recommended that you put some compiler echo so the user
        can know what are the values of the parameters of the function.
        To do this, you can use the internal function called
        ${UseFunc_Echo} using ${_Un} and ${_Name} defines like on
        the following:

        ${UseFunc_Echo} `$ {${_Un}${_Name}} "${myParameter}"`

        You can't put the $ together with {${_Un}${_Name}} because it
        will be transformed to the actual define, and so a compiler
        error would happen.

        Also, for the call, you can use ${_Un2} and ${_Name} defines.
        For example:

        Call ${_Un2}${_Name}

        This would call the parent function.

        After you put the function call code, you are required to put
        the ending ${_UseFunc_Func_End} instruction. This is just to
        make the verbosity of the function to the normal level.

        There is a way of making a call to be for installations or
        uninstallations only. Use the ${UseFunc_RemoveFunctionDef}
        (there is also a version for headers:
        ${UseFunc_RemoveHeaderDef}). To remove the uninstaller
        version of a function, just append the ${_UseFunc_UnPrefix}
        to the start of the function name. Example:

        ${UseFunc_RemoveFunctionDef} `${_UseFunc_UnPrefix}NameOfTheFunction`

        This just removes the function definition only. No changes
        will be done to lists.

      1.1.1.5 Include the header in "UseFunc\_List.nsh" file
      ------------------------------------------------------

        This file is responsible for holding a list of file
        inclusions that use the UseFunc header. Those headers
        are included automatically when "UseFunc.nsh" file is
        included to the user's script. You are responsible for
        taking care of the functions dependencies.

    1.1.2 Creating two versions of a function separatedly
    -----------------------------------------------------

      You just wonder that the features described here use
      only functions with the same version for both installer
      and uninstaller. There is a way to make the separation
      available, by creating a different function with a
      different name and removing parts of definitions from
      both functions.

      1.1.2.1 Remove the uninstaller definition of a function
      -------------------------------------------------------

        First, remove the uninstaller definition of the function,
        or a new function definition won't have any effect.
        That's because the design of the header allows users
        to override the definition of functions, and new
        function definitions won't be applied if those are
        not removed first.

        You could do that in 2 ways:

        - Using ${_UseFunc_DefFunc_NoUn} instead of
          ${_UseFunc_DefFunc} or ${_UseFunc_DefFunc_NoFunc_NoUn}
          instead of ${_UseFunc_DefFunc_NoFunc}.
        - Using ${UseFunc_RemoveFunctionDef} macro.

        Both ways just remove uninstaller definition of a function.

      1.1.2.2 Create a new header for the uninstaller versions of functions
      ---------------------------------------------------------------------

        Why would you need to create a new header just for the
        uninstaller versions of functions? Because all functions start
        with the header name + function name to create the full function
        name. Use the ${_UseFunc_DefHeader_DifName} and provide a fake
        name with the ${_UseFunc_UnPrefix} on its start and the real
        header name.

        This will also allow the better organization of functions
        because installer functions are located in one header, and
        uninstaller's are in other.

      1.1.2.3 Create a new function with the uninstaller definition only
      ------------------------------------------------------------------

        To create a function with the uninstaller definition replacing
        the installer's (thus making it "uninstall supportable only"),
        use the ${_UseFunc_DefFunc_Un} or ${_UseFunc_DefFunc_NoFunc_Un}
        macros instead of the original ones.        

    1.1.3 Using UseFunc functions/headers special features
    ------------------------------------------------------

      1.1.3.1 Re-using a header/function and header/function detection
      ----------------------------------------------------------------

        Do you think the list of features is over? You can also create
        more functions with a header or function that was already
        created before, so you can create more functions as you
        desire if it is a header, for example.

        To do that, just re-create the header or function with the
        same name as used before, isn't that simple?

        To verify the number of times the header or function was
        used, or if it was created, just verify the value of 
        ${NameOfTheHeader_HeaderDefined} define for headers and
        ${NameOfTheFunction_FunctionDefined} define for functions.
        The number of "|" defines the number of times defined
        (what a creativity to overcome the inability to make
        calculations in compile-time!).

        With this, you can also detect if the name
        of a function was been used by a header, vice-versa or
        if both header and function have the same name. Just
        verify if one or both of those defines are present.

  1.2 For Users
  -------------

    1.2.1 Using UseFunc header features
    -----------------------------------

      1.2.1.1 !include "UseFunc.nsh"
      ------------------------------

        To start using all the features of UseFunc header, first you
        should include the file "UseFunc.nsh" to your script. This
        header will automatically load all headers that use the
        UseFunc header features.

      1.2.1.2 Include a function
      --------------------------

        To include a function is easy, just put ${NameOfTheFunction}
        after the inclusion of UseFunc header and outside sections
        and functions. If the function doesn't have a function call,
        means, the call calls directly the function without having a
        function that handles the call, you should skip this step.

        To use the uninstaller version of the function, attach the
        "Un" prefix to the function name, like on
        ${UnNameOfTheFunction}.

        The proper function call will be used for both the installer
        and uninstaller.

      1.2.1.3 Use the function
      ------------------------

        Using the macro-function is a simple task, just use
        ${NameOfTheFunction} again, but now with its parameters, like
        described in the header's documentation (if it exists).

        Some macro-functions can be used anywhere in the code, or
        just inside sections or functions. Those that don't need to
        include a function call can be generally called anywhere, but
        those that need have the restriction.

    1.2.2 Using UseFunc functions/headers special features
    ------------------------------------------------------

      There are special features that only the use of UseFunc can
      provide for users.

      1.2.2.1 Compatibility with older/newer versions of functions
      ------------------------------------------------------------

        Part of the feature depends on if the function you want to be
        compatible with handles this, but you can make restrictions
        for those who compile the code to give warnings for debugging
        purposes. You can use the ${NameOfTheFunction_Ver} to get the
        entire version number, or using the following, to get the
        values for individual version levels:

        Version number of "NameOfTheFunction" function (example):
        1.0.42.2783

        ${NameOfTheFunction_Ver} = 1.0.42.2783
        ${NameOfTheFunction_VerMax} = 1
        ${NameOfTheFunction_VerMin} = 0
        ${NameOfTheFunction_VerBet} = 42
        ${NameOfTheFunction_VerAlp} = 2783

        To give a warning if the version changes for debugging purposes,
        you can use the "compile-time string comparasion trick", as
        shown below:

        !ifdef NameOfTheFunction_Ver
          !define v=${NameOfTheFunction_Ver}
          !ifndef v=1.0.42.2783
            !warning `NameOfTheFunction version ${NameOfTheFunction_Ver} \
                     is not supported by the script. Version currently
                     supported is 1.0.42.2783.`
          !endif
          !undef v=${NameOfTheFunction_Ver}
        !endif

        If the function support the handling of the compatibility, it may,
        or may not, return a value considered as an error. To get more
        information about error handling, consult the documentation of
        the header which contains the function (if it exists).

        This information also applies to headers.

      1.2.2.2 Lists of functions supportable by an header or by UseFunc
      -----------------------------------------------------------------

        All headers and the UseFunc itself have lists of all
        functions supported by the header or UseFunc. To access
        these lists, you can use ${NameOfTheHeader_List}, to access
        the list of functions for that header, or ${UseFunc_List},
        to access all the list with all the functions used with
        UseFunc.

        There are some utilities of having this:
        - You can verify if a function was removed or not from a
          header of UseFunc.
        - You can verify the versions of all functions.
        - You can call one of the functions dynamically. This is
          not totally supported by NSIS: you need to have the
          same amount of parameters for every function.

      1.2.2.3 Lists of headers supportable by UseFunc
      -----------------------------------------------

        UseFunc has a list of all headers supported by itself. To
        access this list, you can use ${UseFunc_List}.

        There are some utilities of having this:
        - You can verify if an header was removed or not from
          UseFunc.
        - You can verify the versions of all headers.

      1.2.2.4 __buitin__ header
      -------------------------

        This header is used by the UseFunc header itself.

        1.2.2.4.1 Defines
        -----------------

          These are the defines that accompany UseFunc.
          Change them before including UseFunc:

          1.2.2.4.1.1 USEFUNC_VERBOSITY "Verbosity"
          -----------------------------------------

            This applies the verbosity to all functions that use
            UseFunc. You can change the value anytime by undefining
            and redefining this define with a new value or by
            defining this define before including UseFunc.

          1.2.2.4.1.2 UseFunc_NoInclusions
          --------------------------------

            This will make the header not to include all the
            headers that use UseFunc. Use this if you want to
            choose the default inclusion of each header you
            wish to include manually.

          1.2.2.4.1.3 _UseFunc_UnPrefix
          -----------------------------

            Specifies the prefix used by uninstaller functions' names.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.4 _UseFunc_UnFuncPrefix
          ---------------------------------

            Specifies the prefix used by uninstaller functions' calls.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.5 _UseFunc_FuncPrefix
          -------------------------------

            Specifies the prefix used by function macro names.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.6 _UseFunc_FuncPostfix
          --------------------------------

            Specifies the postfix used by function macro names.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.7 _UseFunc_FuncCallPrefix
          -----------------------------------

            Specifies the prefix used by function call macro names.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.8 _UseFunc_FuncCallPostfix
          ------------------------------------

            Specifies the postfix used by function call macro names.
            You can change this parameter only before including UseFunc
            in your script.

          1.2.2.4.1.9 TRUE
          ----------------

            Used by commodity in functions that work with booleans and
            the developer wants the function to appear better. You can
            change this parameter before including UseFunc, but it's
            not recommended.

          1.2.2.4.1.10 FALSE
          -----------------

            Used by commodity in functions that work with booleans and
            the developer wants the function to appear better. You can
            change this parameter before including UseFunc, but it's
            not recommended.

          1.2.2.4.1.11 ERROR
          ------------------

            Used by commodity in functions that work with return
            values and the developer wants the function to appear
            better. You can change this parameter before including
            UseFunc, but it's not recommended.

        1.2.2.4.2 Macros
        ----------------

        These are the compile-time only macros that accompany
        UseFunc which can be used by users. The creation of
        headers is explained in the developers section:

          1.2.2.4.1 ${UseFunc_Echo}
          -------------------------

            This macro uses !echo from NSIS, but the difference is
            that UseFunc's header verbosity is applied to it. Use
            this if you have a verbosity lower than 4 and you
            want this echo to show up.

          1.2.2.4.2 ${UseFunc_Warning}
          ----------------------------

            This macro uses !warning from NSIS, but the difference is
            that UseFunc's header verbosity is applied to it. Use
            this if you have a verbosity lower than 3 and you
            want this warning to show up.

          1.2.2.4.3 ${UseFunc_Error}
          --------------------------

            This macro uses !error from NSIS, but the difference is
            that UseFunc's header verbosity is applied to it. Use
            this if you have a verbosity lower than 2 and you
            want this error to show up.

          1.2.2.4.4 ${UseFunc_List_Attach}
          --------------------------------

            This macro attaches a string to a define, like for the
            lists of functions.

          1.2.2.4.5 ${UseFunc_RemoveFunctionDef} "FunctionName"
          -----------------------------------------------------

            This macro removes a function definition. This just
            removes the installer or uninstaller version of
            a function. If you want to remove the uninstaller
            version of a function, put ${_UseFunc_UnPrefix}
            to the left of the name. Like
            ${_UseFunc_UnPrefix}FuncName, for example.

2. Versions History
-------------------

1.0 - 10/Aug/2005

- First version.

3. Credits
----------

  - UseFunc header macro-function wrapper created by deguix.
  
4. License
----------

  This header file is provided 'as-is', without any express or implied
  warranty. In no event will the author be held liable for any damages
  arising from the use of this header file.

  Permission is granted to anyone to use this header file for any purpose,
  including commercial applications, and to alter it and redistribute
  it freely, subject to the following restrictions:

  1. The origin of this header file must not be misrepresented;
     you must not claim that you wrote the original header file.
     If you use this header file in a product, an acknowledgment in the
     product documentation would be appreciated but is not required.
  2. Altered versions must be plainly marked as such,
     and must not be misrepresented as being the original header file.
  3. This notice may not be removed or altered from any distribution.