Re: [Gnu-arch-users] [BUG] feature plan -- version variables

[Tom Lord]

    > From: Aaron Bentley <address@hidden>

    > Tom Lord wrote:

    > > * Range

    > >   The value of a version variable must be a Pika Scheme s-expression
    > >   satisfying certain constraints:

    > >         1) Only cons pairs, booleans, small integers,
    > >            nil, and strings containing only iso-8859-1
    > >            characters may occur in the value.

    > Why iso-8859-1?  Since we plan to make patchlogs utf-8, 

(We do?  That may be where we left off the discussion but I don't think
any final decision has been made.  That proposed decision strikes me
as a poor one, at the moment.)


    > I'd imagine limiting it to ASCII until we make patchlogs utf-8.

You're confused.

You're talking about how a version variable value is written.

I'm talking about what the version variable value may contain.

Here is a valid Pika Scheme string constant written using nothing but
ASCII characters:

        "\(U+03A4)"

but that string wouldn't be permitted as a version variable value
because it contains a non-iso-8859-1 character (a capital Greek Tau).

This one:

        "\(U+00DF)"

would be permitted.

(The reason for this restriction is not to control the contents
of patch-logs but to simplify the C interface for manipulating these
lisp-like values.   I don't want to drag in a dependency on a Unicode
based interface just yet.)



    > > * Representation

    > >   Within a project tree, variable values are usually found by
    > >   reading the patch-log.   The latest patch-log entry for the 
    > >   tree-version of the project tree may contain a header:

    > >         set-in-version: (<name> <value>)*

    > Are those parentheses literal charaters or part of the definition 
    > syntax?  

The latter.

    > (I'm wondering what the separator is.  Personally, I'd probably 
    > do it one-var-per-line instead)

Scheme syntax doesn't require newlines to be significant that way.  A
stream of datums parses unambiguously with one character lookahead.

Some data types (e.g,. symbols) must be followed in the stream by 
any of 

        <whitespace> ( ) " ;

So , the parser can just read pairs of datums from set-in-version
headers until they're used up.   Users can use newline separation of
pairs and values if they want to, but don't have to.

These are equivalent:

        set-in-version: foo(1 2 3)bar"hello world"x1y()

and:
        set-in-version:
                foo             (1 2 3)
                bar             "hello world"
                x1y             ()


    > Are those map semantics?  I'd imagine if the same name appears multiple 
    > times, only the last assignment is used?  Or is it an error?

Interesting question.

I think the way to do it is:

1) `commit' and friends won't commit a changelog that sets the same
   name twice.

2) When _reading_ a variable value, ./{arch}/++variables takes
   precedence but if the variable isn't set there, and is set
   twice in the most recent log entry, then that variable can't
   be read.


    > Care to specify a representation for lists, or do you think the list 
    > user should chooose it?

I have no idea what you mean.  Lists are written with parentheses.
Internally, all datums will be something like:

        struct simple_lisp_datum
        {
          enum simple_lisp_type type;

          union
          {
            t_uint32 small_int;
            t_uchar * iso_8859_1_string;
            int boolean;
            t_uchar * symbol_name;
            struct simple_lisp_pair
            {
              struct simple_lisp_datum * car;
              struct simple_lisp_datum * cdr;
            }
          }
        }

I'm not sure what part you think a user would choose.


    >>   Variables without an explicitly set value have the value false
    >>   (`#f').

    >>   If the file ./{arch}/++variables exists then it should contain
    >>   0 or more valid `set-in-version' log message headers -- these
    >>   override the settings in the latest patch log entry.

    > Is this file immortal, or is it deleted by commit/import?

Probably deleted by commit/import but only after being copied into the
log message.

Should there be some that are purely local to a tree (not deleted, not
copied to the log)?   Perhaps....  but that's easy enough to add
later.

A related question is whether or not (or which) variable values should
be copied from one branch to another by `tag'.



    > >   % tla version-var name value
    > >   [locally set the value of name to value]

    > >   % tla version-var --unset name
    > >   [remove any local setting for name]

    > Would this delete a version-var?
    > % tla version-var name #f

    > (Is there any difference between a false value and a missing value?)

If a variable is _not_ set locally, then its value is determined by
the most recent patch log entry.

So, 

    % tla version-var foo #f

sets foo to #f but:

    % tla version-var --unset foo

ensures that foo is taken from the patch log.   If it isn't found
in the patch log then it's #f --- but if its in the patch log it
can have any value.

E.g.:

    % tla get SOMEREVISION wd

    % cd wd

    # the default value, inherited from the patch log:
    # 
    % tla version-var foo
    (1 2 3)

    # local settings:
    # 
    % tla version-var foo hello

    % tla version-var foo
    hello

    % tla version-var foo '#f'

    % tla version-var foo
    #f

    % tla version-var --unset foo

    % tla version-var foo
    (1 2 3)


-t