Non-ideal discoverability of Janet divergences from other programming languages about janet-lang.org HOT 9 OPEN

The behaviour of the match operator for shorter tuples would also be relevant here.
This is explained in janet.guide/control-flow at “This is terrible, and you will mess this up at some point”

from janet-lang.org.

Ok, time to pop my head out for a moment! :) I've seen two of these elsewhere, and thought they were pretty useful (full disclosure, years ago I wrote a few of the ones for Ruby (though I expect they've been updated a bit since then)) :

• https://www.ruby-lang.org/en/documentation/ruby-from-other-languages/ -- I particularly like the clarity of the headings for these, for example: "Similarities: As with Python, in Ruby,…" and "Differences: Unlike Python, in Ruby,…".

• Just recently saw these too: https://docs.julialang.org/en/v1/manual/noteworthy-differences/ .

The ones for Julia are more lumped together -- I think the ones for Ruby are more nicely organized. :)

from janet-lang.org.

Along the lines of improving the existing documentation for the case of providing some explanation of how negative indices work in Janet, I think this section is a candidate for an addition.

from janet-lang.org.

@uvtc Thanks for sharing those, will be working on digesting them.

P.S. Good to hear from you -- been missing your presence!

from janet-lang.org.

Aw, thanks, sogaiu!

from janet-lang.org.

I'm not sure yet whether the following should count, but I'll note it for future reference...

The */slice functions all have an optional start argument. The docstring for string/slice is currently:

    (string/slice bytes &opt start end)

    Returns a substring from a byte sequence. The substring is from 
    index `start` inclusive to index `end`, exclusive. All indexing is 
    from 0. `start` and `end` can also be negative to indicate indexing 
    from the end of the string. Note that if `start` is negative it is 
    exclusive, and if `end` is negative it is inclusive, to allow a 
    full negative slice range.

For the non-negative value cases, start can range from 0 through the length (NOT limited to 1 less than the length -- this is not mentioned in the docstring) of the argument being sliced.

For example, if slicing something of length 1, start can be 0 or as shown below, 1:

$ janet
Janet 1.32.1-11d7af3f linux/x64/gcc - '(doc)' for help
repl:1:> (string/slice "a" 1)
""
repl:2:> (array/slice @["a"] 1)
@[]
repl:3:> (buffer/slice @"a" 1)
@""
repl:4:> (keyword/slice :a 1)
:
repl:5:> (tuple/slice ["a"] 1)
()
repl:6:> (type (symbol/slice 'a 1))
:symbol
repl:7:> (length (symbol/slice 'a 1))
0

This was unexpected to me [1], but thinking of the value of start as representing or pointing to a space or gap between elements made it less odd, e.g. for a string:

byte position:  0 1 2 3 4 5 6 7 8
----------------------------------
       string:  ( d e f   a   1 )
      indeces: 0 1 2 3 4 5 6 7 8 9

In the case of a string of length 1, that might look like:

byte position:  0
------------------
       string:  x
      indeces: 0 1

I'll note that this may not be a divergence from other programming languages, possibly it might be considered a gotcha (but may be not).

[1] On a side note, it looks like one may produce a symbol of length 0:

repl:6:> (type (symbol/slice 'a 1))
:symbol
repl:7:> (length (symbol/slice 'a 1))
0

That seems a bit odd to me. Not sure if that's problematic...

from janet-lang.org.

The behaviour of the match operator for shorter tuples would also be relevant here. This is explained in janet.guide/control-flow at “This is terrible, and you will mess this up at some point”

Hi @tionis,
you're right, match macro is ... funny to use too :)

from janet-lang.org.

I think it would be convenient for users to be able to discover divergences (to adopt the terminology of the issue's title) and/or potential gotchas.

I'm not really sure how to do this well though.

A single list might be nice, though for some things, perhaps one would want to learn about individual items in context (e.g. there is an example of slicing with a negative index in an example of this section). I suppose there could be a list which is pointed at from specific sections (or a specific part of the list could be linked to).

Note though that for negative index use, this might lead to a fair bit of extra text spread across multiple sections. That might not be so great from a maintenance perspective if certain changes were to be made later.

I hope it's clear from the little examination above that it's not necessarily a no-brainer to do this kind of thing in a maintainable manner. That's not to say that things couldn't be improved, just that there may not be a single easy-to-execute approach. Still, perhaps a good idea will come about or individual items might be improved upon.

For the moment, may be this issue could collect some potential content -- though if it's distributed throughout the issue, it may become unwieldy to act upon items from a practical perspective....

from janet-lang.org.

Looking at the Ruby and Julia resources I was reminded of this.

from janet-lang.org.