find, starts-with, ends-with, replace

Notices and updates
Locked
xytroxon
Posts: 296
Joined: Tue Nov 06, 2007 3:59 pm
Contact:

find, starts-with, ends-with, replace

Post by xytroxon »

While reviewing the newLISP manual, I have noticed a function argument "natural order" puzzle for confusing newbies and frustrating oldies ;)

Given:

Code: Select all

(setq in-my-text "this is useful")
Find a string in text :

Code: Select all

(find "this" in-my-text)
Okay. But starts-with (and ends-with) form is:

Code: Select all

(starts-with in-my-text "this")
Shouldn't starts-with follow the find argument order?

Code: Select all

(starts-with "this" in-my-text)
The reason I ask is that I prototype my regex's using find. And after I optimized some old code that used find to starts-with (by simply changing the find keyword to start-with) , I had a hard time finding the problem because the code still "worked" but would not match anything!

Also, when building the string to be searched in place

Code: Select all

(starts-with (string in-my-text "xyz" (somestringfunc)) "this")
"this" gets lost in the string noise... While:

Code: Select all

(starts-with  "this" (string in-my-text "xyz" (somestringfunc)))
Remains understandable...

And while I am "on a roll" (ranting :)

replace also suffers from "string noise" syndrome.

Code: Select all

(replace "this" (string in-my-text "xyz" (somestringfunc)) "with that")
While this form just looks cleaner and clearer to me.

Code: Select all

(replace "this" "with that" (string in-my-text "xyz" (somestringfunc)))
--xytroxon
"Many computers can print only capital letters, so we shall not use lowercase letters."
-- Let's Talk Lisp (c) 1976

unixtechie
Posts: 65
Joined: Sat Sep 06, 2008 6:30 am

On (starts-with in-my-text "this") and other such

Post by unixtechie »

(starts-with in-my-text "this")
..more important, I think, is that pseudo-code self-explanatory formulas
were included into the manual as well as in the short help one-liners.


This (verbs, nouns, verb phrase) is how brain operates naturally, and writing documentation "formally", i.e. requiring the poor sod of user to:
(a) learn the special lingo to speak ABOUT the target language
(b) read the stuff in the lingo, which speaks "about" but not to the point
(c) do the internal translation into exactly this kind of pseudo-code:
"Aha! so this is "match this in-this-(buffer)-string".

Now he "understood"! Eureka!!

This problem, or a slightly more general problem of right "entry" is the major problem in presenting any information.
It's like they gave you a task to find all telepnones in a certain area by reading an alphabetic telepnone book. Of course, the information is there, but to get the needed prefix you'd have to scan THE WHOLE of it.

These 2 defects literally kill good programming ideas. Both are present in the formal decumentation that "follows (government) standards", try to find a practical description of LISP!

The Internet Age made people without formulating it as a principle spontaneously re-write explanations in a much more practical way.
"Cookbooks", documentation and "intro" texts for the modern scripting languages are of incomparably better quality than those of the previous age (requiring to learn the birdy talk of descriptions "about" and back-translating into concrete examples).

However even now the principle is not implemented fully because people lack explicit understanding of the above.

We can with little effort make all NewLisp operator definitions self=-explanatory.

I did this for an earlier version of the manual, but it will need redoing now.


P.S. Interesting that the same realization happened in linguistics, too. A pioneering project in Birmingham University (they were one of the first to use computers to analyze actual usage pattern of English in the 1980s, by the way).
Their word definitions being definitions at the same time describe the actual collocation and usage patterns as well.

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

Great thoughts and comments from Xytroxon and Unixtechie!

Normally I try to make the sequence of parameters the way you would talk in a natural language:

starts <text> with <this>? => (starts-with text this)

or

find <this> in <text> => (find this text)

But one cannot go by just one principle when designing an API or the syntax of a specific function. There are several principles according to which you can build an intuitive API. All of these have to be balanced against each other:

(1) closeness to natural language
(2) easy/short to type and memorize
(3) consistency inside a family of functions
(4) redability of composite expressions
(5) fits into programming languages culture

... etc. add your own ;-)

Regarding documentation style: The reference documentation tries to balance between a formal (government) and more casual approach. Probably a lot can be improved here. Its a never ending task.

In Cormullion's "Introduction to newLISP" we find the casual, entertaining approach, very suitable for an introduction to a complex technical topic. For my taste it came out pretty perfect and should go into print. Its among the top downloads on newlisp.org.

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

Lutz wrote:In Cormullion's "Introduction to newLISP" we find the casual, entertaining approach, very suitable for an introduction to a complex technical topic. For my taste it came out pretty perfect and should go into print. Its among the top downloads on newlisp.org.
Cool! The next version is in Technicolor - well the code listings are.

Locked