baco Files

baco (0.1)______________________________________________________________________

Is the interpreter of a scripting language, born to perform backup/copy
operations.

You may use the language to write any baco-file, where you declare sets of
procedures. Each procedure is basically a set of copy/backup operations.
To use those procedures, open a terminal and move to the installation's folder.
Launch the interpreter (a Python script) using this command:

  Under Linux:
    $  python  baco.py  [options]  [procedures]

  Under Windows:
    >  python.exe  baco.py  [options]  [procedures]

python | python.exe
  Must be substitued with your actual Python executable name.

baco.py
  The main baco module.

[options]
  Optional command line options (see below).

[procedures]
  Optional list of procedures to be directly executed.


Version:
  0.1
Operating systems:
  Linux, Windows
Requires:
  Installation of Python 3.2 or later
  Under Windows: also the installation of Python's win32api extension in order
  to use the device-label utility.
Release date:
  05/Feb/2013

________________________________________________________________________________
___features_____________________________________________________________________

  *  Accepts device labels

(This should be useful for removable devices.)
Example:  !DATA/folder
where 'DATA' is a device label. Must be preceeded by the '!' character.
A check is performed, that a device with that label is actually mounted.

  *  You can define properties.

Useful for aliasing of long paths or to change at-once a path used many times.
Properties can be used only at the beginning of a command parameter after the
"-" tag.
Example, using a cd command:

............................................................
define
    pen     !KINGSTON/aaa
cd          -pen/bbb
............................................................

"-pen/bbb" will become "!KINGSTON/aaa/bbb" (which will possibly be expanded to
"/media/KINGSTON/aaa/bbb" under Linux or to "F:\aaa\bbb" under Windows, after
the device mounting check has been performed).

  *  Ftp transfers too

For this purpose, you must define the 'web' property as the address of the web
location. Define username and password too.

............................................................
define
    web         www.my-site.com
    ftp_port    2121
    ftp_user    adm@my-site.com
    ftp_pass    123456
............................................................


  *  You edit your copy/backup procedures simply and fast, using a text editor.

The interpreter will check the syntax and help you to find possible errors.

________________________________________________________________________________
__the dialect___________________________________________________________________

Example of a baco-file:

............................................................
define
    my          /home/my-username
procedure       copy-hello-to-pen
define
    pen         !KINGSTON/backup
cd              -my/projects
copy
    options     fullpath
    ignore      *.pyc;*.bah
    from        hello
    to          -pen
............................................................


Another example, with the simplest syntax. Under Linux.
If "/media/KINGSTON" is intended as the mount point of a removable device, but
the device is not mounted, baco will try to create a folder with that name.
No check of device existence will be made. Use device label syntax to avoid
this problem.

............................................................
procedure       copy-hello-to-pen
copy
    from        /home/my-username/projects/hello
    to          /media/KINGSTON/backup/hello
............................................................


A similar example, under Windows.
If "F:" is intended as a precise removable device, using this syntax you won't
know when that device has been mounted at "F:". Use device label syntax to
avoid this problem.

............................................................
procedure       copy-hello-to-pen
copy
    from        C:\Users\my-username\projects\hello
    to          F:\backup\hello
............................................................

________________________________________________________________________________
__»__commands___________________________________________________________________

define
  This command declares the beginning of a block of property definitions, in
  the form: name => value.
  The first define-block, before the procedures, defines global properties,
  available to all the procedures.
  The define-block which is inside a procedure, defines properties local to
  the procedure.

procedure
  This command declares the name of a new procedure.

cd
  Sets the working directory (for the original path) for all the following
  backup/copy operations, till a new cd command is found.

copy
  This command declares the beginning of a block of sub-commands for a
  copy-operation.
  Sub-commands:

    ignore
      A list of patterns to be ignored. Separated by just a semi-colon.
    options
      A list of options. Separated by just a semi-colon.
      Possible options are:
        fullpath
          Maintains for the destination path the original path.
          from a/b/c to z  =>  destination path is z/a/b/c
    from
      The original item. May be a file, a pattern, a folder.
    to
      The destination path.

backup
  This command declares the beginning of a block for a backup operation.
  Sub-commands are the same as for the copy command.
  To the destination path, 2 subdirectories are appended:
  - the name of the procedure between a "__" prefix and suffix:
    __procedure-name__
  - the date-time stamp of the moment when the backup is done:
    20130620_2045  (year-month-day_hour-minute)

  Example:
  ............................................................
  procedure       hello
  backup
      from        hello_files
      to          backup
  ............................................................

  The destination directory-tree, after 2 backups, will look like this:

    backup/
        __hello__/
            20130620_2045/
                hello_files
            20130624_2036/
                hello_files

________________________________________________________________________________
__»__syntax_____________________________________________________________________

A baco-file is made of words. Some words are commands, the rest are parameters.
Some commands have no parameter but declare the beginning of a block:

  define
    Begins a block of property definitions.

  copy, backup
    Begin a block of sub-commands.

The other commands are followed by a single parameter.
No spaces are allowed inside a word.
(Possibility to use spaces in a word will be available in a future release,
using quotations.)

The interpreter parses the words it finds in the baco-file and put them in a
sequence of words, indipendently to which whitespaces do separate them.
Thus, the structure and the indentation of the text are not considered by the
interpreter.

Lines starting with '#' or '_' are not considered.

________________________________________________________________________________
__command-line options__________________________________________________________

  -file=filename

Where filename is the baco-file to be used.
Default baco-file is "main.baco".

  -verb=#

Where # is a number defining the verbosity of the output.
  0 = minimalist user info
  1 = detailed  user info
  2 = add some minimalist debug info
  3 = add detailed debug info
Default value is 1.