Hi Tim, Tim Cross <theophil...@gmail.com> writes:
> It seems to me that two separate issues have been mixed up and causing > some confusion here. However, I think it is actually quite simple once > we consider the issues separately. > > Issue 1: Defining the meaning of :result value and :result output > Issue 2: Specifying what the default :result setting would be i.e. > :result without a value/output specifier. > > Issue 1 seems the most straight-forward to me > - output :: Whatever goes to stdout/stderr > - value :: whatever would be returned by the execution of the code. This > might be a return value (i.e. for some shell commands) or the value > returned by a function (including shell functions i.e. bash function) or > the last command executed etc. Essentially, anything returned (including > nil) by the block. STDOUT/STDERR is never a return value (though some > languages may send output to STDOUT/STDERR as well as returning it, in > which case it would also be in :return value). > > Note that I don't agree that the only 'useful' result from shell blocks > is output. You might have a complex shell script which uses source > blocks to define shell functions > that return values which you use via oweb expansion to include in other > blocks etc.s > > With this definition, essentially :result value is essentially anything > except whatever is sent to stdout/stderr. > > Issue 2 is a little more difficult. It is likely that a 'standard' > default for :result that is the same for all languages is not > possible/desired. The default will likely be a combination of what seems > most natural for that language and what is most common usage for the > majority of users. It could be that for some languages, the default for > :result should be :result output and for others it should be :result > value. > > Personally, I care less about issue 2 than issue 1. In the worst case, I > will need to change my header arguments for some blocks and that would > be easily automated. Far more critical is that :result value and :result > output are clear, unambiguous and consistent. Any proposal to change > these meanings because of different uses cases in languages is a bad > idea. Instead, changing the 'default' would be preferable. Having shell > source blocks return STDOUT/STDERR output for :result value is IMO a bad > idea. Having shell blocks default to :result output when only specifying > :result while having other languages, like python or clojure default to > :result value seems far more preferable (provided differences are > clearly documented of course). > ... Thanks for the (very clear) write-up. I can only nod my head in violent agreement :-) -- Nick "There are only two hard problems in computer science: cache invalidation, naming things, and off-by-one errors." -Martin Fowler
