Arc Forum | Anarki Conventions

Arc Forum

10 points by nex3 6125 days ago | 19 comments

I've just added a CONVENTIONS file to Anarki that will detail various coding and repo-management conventions for the wiki. I think it's important to have these conventions; otherwise, the styles are inconsistent, which is bad.

You can view the file online at http://git.nex-3.com/arc-wiki.git?a=blob;f=CONVENTIONS. I haven't added nearly as much stuff as I plan to as of this writing, but hopefully I will fairly quickly.

Most of the conventions will be based on the existing code as written by PG, except for those for which there aren't examples in PG's code (e.g. Git commits) and for which PG's solution would get unwieldy for larger amounts of code (e.g. putting libraries in the main directory).

If you have any suggestions for additions and so forth, please post them here and/or update Anarki (if you do the latter, it would probably be good to do the former as well).

7 points by ambition 6125 days ago | link

As a principle to consider, how about: "Any change to anarki should not break any program which runs correctly on the latest arcn, if the program does not exploit bugs in arcn."

What do you think?

-----

3 points by almkglor 6123 days ago | link

You know, any change to anarki which adds macros, of all things, would break some programs that run correctly on the latest arcn.

For example, suppose I were to define a simple macro, nothing:

  (mac nothing () nil)

Then the following simple program will run correctly on arc1, but fail if you define the above macro:

  (def doda (xs)
    (let nothing (table)
       (each x xs (assert (nothing x)))
       nothing ))

I think the above issue definitely needs to get fixed.

-----

2 points by raymyers 6123 days ago | link

True. Anarki-only macros should probably be banished to the `lib' folder, so they have to be (require)'d before they start modify your code.

-----

2 points by nex3 6123 days ago | link

I'm not so sure about this. I think changes of the filling-up-namespace sort are reasonable, for the same reason being a Lisp-1 is reasonable: conflicts happen rarely in practice.

A better solution would be to try to ensure that only generally useful macros are added to arc.arc, and that they have names that are unlikely to be used as local variables. Or even better would be to make local variables shadow macros.

Consider this, though: "help" is defined as a macro. Some of the REPL-var code needs macros. The drop-into-scheme operator is a macro. I don't think we want to make people load a library file to use these.

I see the compatibility rule as more of a guideline - try not to break the functionality of stuff that already exists. But I don't think it should limit experimentation and exploration, including exploration of what's useful to have in arc.arc.

-----

2 points by raymyers 6123 days ago | link

OK, I'll backpedal a bit here. The last thing I want is to have to require "lib/help.arc" :). It should be easy to find out what macros have been added though -- as much for curiosity as for compatibility. I'll try and whip up a script tonight, unless someone beats me to it.

-----

4 points by raymyers 6122 days ago | link

Script complete. It crawls `arc.arc' and every file loaded by `libs.arc'. So now, if you type the following,

    (require "lib/new-macros.arc")
    (new-macros)

... you will discover that the non-Arc1 macros in Anarki are currently:

    ($ % % %% %%% breakable defsop help make-br-fn or= redef)

-----

1 point by nex3 6122 days ago | link

Most excellent. It's great to see how easy it is to analyze Arc code using Arc.

Anyway, of those, the only one I see potentially conflicting with a variable name is "breakable", and that seems quite unlikely.

-----

2 points by akkartik 6122 days ago | link

Great thread to see how y'all converged on a design decision after some back and forth.

-----

4 points by raymyers 6125 days ago | link

That's a great requirement, but it might easier to obey if there was a test suite.

-----

4 points by nex3 6124 days ago | link

Please, feel free to make one (or rather, contribute... offby1 has the beginnings there already).

-----

3 points by nex3 6125 days ago | link

I agree. I've pushed something to that effect.

-----

2 points by byronsalty 6125 days ago | link

Ok. The public_html change I made to srv last week will break anyone expecting to serve files out of the root directory (as they would with arc1). Should I revert this change? Then plead PG to pick it up with arc2...

Actually I could default the docroot to "" instead of "arc/public_html". I think it's ugly but if we want to be compatible with arc1 then this would do it.

-----

3 points by nex3 6124 days ago | link

I think this isn't so much a language issue as a configuration issue, so it should be fine.

-----

2 points by raymyers 6123 days ago | link

If anyone notices an issue regarding Anarki's compatibility with Arc, please note it in BUGS. Thanks :)

-----

3 points by almkglor 6125 days ago | link

Forms which have a condition-code form (if, case, p-m) should generally have the code indented more than the condition:

  (if
    (something-or-other foo bar)
        (do (this))
    (some-other-thing bar foo)
        (do (that)))

-----

1 point by tel 6125 days ago | link

I know this has been pg's convention in the code, but in my code I've been keeping the indentation at the same level. Since code tends to shoot off toward the right, you get code that look like:

    (if
      (cond1 ...)
      (map some-fn (generation-fn arg arg arg
                                  (maybe-table key)))
      (cond2 arg (some-fn2 (...)
                           (...)))
      (some-fn3 arg arg))

It's pretty easy to count off condition/result pairs like this, but if you indent the results it gets more difficult to pick them out from the conditions.

-----

4 points by eds 6125 days ago | link

What about end of line conventions? The files should probably all be either unix or dos format. (Right now it looks like the formats are mixed.)

-----

7 points by nex3 6124 days ago | link

I think Unix is probably the best choice, because the official distribution is in Unix format and I imagine more people who use Arc use Unix than Windows.

I'm not sure how easy this is to manage in the text editors most people use, though, so it may not be worthwhile specifying it.

-----

4 points by nex3 6123 days ago | link

On second thought, changing entire files from Unix->Windows newlines screws with Git history, so specifying it's probably a good idea.

-----