Win\Reg - Windows Registry Access Library
                   =========================================
                         File: Win\Reg - Update: 1.02
                    Author: J.G.Harston - Date: 13-Aug-2007


The registry is a repository of data maintained by Windows, which an application
can use to hold configuration or other information from one session to the next.
The registry has a hierarchical structure, not unlike a filing system. Analogous
with directories are keys, which identify locations within the registry. Within
each key there can be a number of named values (analogous with files) each of
which can contain data.

The Win\Reg library provides functions to read and write strings in the
HKEY_CURRENT_USER part of the registry. Note that writing to the registry is
potentially dangerous and can leave your system unusable. 

DEFFNReg_Rd(Key$)
=================
Reg_Rd() reads the specified registry item as a string. If it does not exist, a
null string is returned. For example:

docs$=FNReg_Rd("Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders\Personal")

will read the pathname that 'My Documents' defaults to.

DEFPROCReg_Wr(Key$,Value$)
==========================
Reg_Wr() writes a registry string, creating the entry if it does not already
exist. For example,

PROCReg_Wr("Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders\Personal", \
\ "H:\Docs")

sets the 'My Documents' pathname to 'H:\Docs'.

Naming consistancy
==================
Programs should ensure that the registry keys they use follow a consistant naming
structure. This should be 'Software\Publisher\Application', for example:

  Software\Microsoft\Windows
  Software\R T Russell\BBC BASIC for Windows
  Software\J.G.Harston\MakeIndex

For convenience, a program could set a variable to its registry branch and then
refer to registry entries relative to that, for instance:

  regRoot$="Software\J.G.Harston\MakeIndex\"
  ...
  SaveAs$=FNReg_Rd(regRoot$+"SaveAs")

Example code
============
The following code replicates the registry import function of applications such as
RegEdit. Bear in mind that it only writes strings.

  DEFPROCReg_Import(file$)
  LOCAL Key$,Item$,Value$
  in%=OPENIN(file$):IF in%=0:ENDPROC
  REPEAT
    A$=GET$#in%
    IFLEFT$(A$,1)="[" THEN
      A%=INSTR(A$,"\"):Key$=MID$(A$,A%+1)
      A%=INSTR(Key$,"]"):Key$=LEFT$(Key$,A%-1)
    ENDIF
    IFLEFT$(A$,1)="""" THEN
      A%=INSTR(A$,"="):Item$=LEFT$(A$,A%-1):Value$=MID$(A$,A%+1)
      A%=INSTR(Item$,"""",2):Item$=MID$(Item$,2,A%-2)
      A%=INSTR(Value$,"""",2):Value$=MID$(Value$,2,A%-2)
      REPEAT
        A%=INSTR(Value$,"\\"):IFA%:Value$=LEFT$(Value$,A%-1)+MID$(Value$,A%+1)
      UNTILA%=0
      PROCReg_Wr(Key$+"\"+Item$,Value$)
    ENDIF
  UNTILEOF#in%
  CLOSE#in%:in%=0
  ENDPROC

Notes
=====
The registry stores the item name (the leafname) seperately from the key name (the
pathname), and the item name can actually have '\' characters in it. The Win\Reg
library cannot access these items. The Win\Reg library only writes strings and
assumes that entries it reads are strings. If you want fuller access to the
registry you should use the Win\Registry library.

Disclaimer
==========
Writing to the registry is potentially dangerous and can leave your system
unusable. The Win\Reg library is provided "as-is" and is Copyright (C)
J.G.Harston. No responsibility can or will be taken for any loss, damage, etc,
whatsoever through its use. The Win\Reg library may be freely used and
redistributed in any BBC BASIC for Windows program. Please acknowledge its use in
any documentation. The library is based on code in Appendix E of the BBC BASIC for
Windows manual.

References
==========
R.T.Russell, Appendix E, BBC BASIC for Windows Manual.

Version History
===============
1.00 18-May-2006 Initial version.
1.01 09-Feb-2007 Reg_Rd() finds required buffer size before reading.
1.02 13-Aug-2007 Reg_Rd() localises all its variables.