SearchYC.com

This is how it should always be done. Encoding your ideas in any programming language is a lossy operation: it's difficult or impossible to determine from an arbitrary piece of source code what the intent and purpose of the programmer originally was. Good documentation gives the missing pieces.

I've found it incredibly helpful to write the documentation of functions before the function itself. Like you, I have a small head, and unless I know exactly what I should program beforehand, it's going to be difficult and messy to keep all details in mind. Describe the intent and purpose, give a canonical example of use (single line, or a couple of more if the function is variadic), rule out illegal input, and you're set.

Note that I'm not advocating long pieces of documentation. If you cannot describe a function well in a few lines, it's too big, and it's definitely not clear to you what it should be. If the documentation is in the same place as the source code, it is worlds easier to write the documentation, write the source code, then bounce between them while developing (since both usually require iteration).

It would make more sense to provide the following kind of implicit currying:

  (def f (x y) ...)
  (let (x 'something)
    (= curried-f f.x))

  curried-f!else ; Calls (f 'something 'else)

I'm in favour of the dot syntax as infix function application operator. It reminds me of Edsger Dijkstra's reasoning (in fact, he also used the dot as function application). You may want to read [1] for the full story and other nice pondering about infix operators and syntax.

  (max 1 2) ; --> 2
  1 max 2   ; --> 2

  1 max 3 max 2 max 5 ; --> 5 

  max{  }

  max{ x :  } .

Coming back to Lisp and Arc, is familiarity the only reason you want infix math operators? The biggest benefit you get from prefix compared to infix is its regularity and uniformity. Control structures, function calls, and (now in Arc) array and hash table access are all identical. This means you can freely add not only new functions, but new control structures, without hacking the parser and the compiler.

One reason why this happens is that you don't have precedence levels. Precedence is always explicit (bar Arc's new intrasymbol operators, which are infix), and this is why Lisp mathematical functions, such as + and *, accept multiple arguments. The distinction between (+ 1 (+ 2 3)) and (+ (+ 1 2) 3) is useless and even harmful. It's best to write it (+ 1 2 3) or 1 + 2 + 3, because the operation is associative.

The "f:g" syntax is a nice idea for function composition, as is "~f" for negation, but the current syntax and semantics seem like a hack. What if we could do this instead:

  (def f (x y) ...)
  (infix f left)

    ; The compiler would transform this to (f x y)
    ; And this to (f (f x y) z) (evaluate from the left)

  (infix f right)

    ; And now to (f x (f y z)) (evaluate from the right)

  ; Use in "normal" syntax:
  (= foo )  ; --> (= foo (f x y))

  ; So, we could do this:
  (infix + right)
  
  (= foo <1 + 2>)  ; Would evaluate/transform to (= foo (+ 1 2))

  (= foo (+ 1 2 3 4))  ; And we could still use the ordinary function call syntax.

  ; Or maybe even:
  (infix + associative)
  (= foo <1 + 2 + 3 + 4>)  ; Transforms to (+ 1 2 3 4) if the function is n-ary, or 
                           ; some arbitrary evaluation order if not.

  ; And now for the interesting bit.
  (def : (f g) (fn (x) (f (g x)))))
  (infix : right)

  (map  list)  ; What currently is (map f:g list)

  ; Why not extend the idea?
  (def ~ (f) (fn (x) (not (f x))))
  (unary ~)

  (if (<~ predicate> arg) ...)

  ; No, that doesn't have any benefit over ((~ predicate) arg).

- How do you define precedence levels? Once you are in this swamp, you can't get out. Maybe all infix functions would have the same precedence to side-step the issue.

- Is it possible to do with only the < > notation? But how would you parse the following without the additional information that + is infix?

  <+ + + + +> 

  (doc ""
    (def fun args ...))

Ferrying complex objects with binary data over the link is not going to be pleasant in that scheme, though. And it would be difficult to conceive a generic function call protocol without reinventing RPC or SOAP.