brownplt / pyret-docs Goto Github PK

This is a very nice section:

https://www.pyret.org/docs/latest/equality.html#%28part._s~3aroughnum-equality%29

I think it would benefit from saying there are two kinds of comparisons possible, and linking to

https://www.pyret.org/docs/latest/equality.html#%28part._s~3abounded-equalities%29

I also wonder if the error message for roughnum equality couldn't link to the first link above? (Yes, it's controversial to have links in error messages… But it's such good prose, and a student who doesn't know what is going on is going to miss out on it.)

In https://www.pyret.org/docs/latest/s_spies.html, the code example:

fun reverse(lst, sofar):
  spy "lengths":
    lst-length: lst.length(),
    sofar-length: sofar.length(),
    sum: lst.length() + sofar.length()
  end
  cases(List<A>) lst:
    | empty => sofar
    | link(first, rest) =>
      reverse(rest, link(first, sofar))
  end
end

check:
  reverse([list: "a", "b", "c"], empty) is [list: "c", "b", "a"]
end

has an unbound id A in List<A>.

It would be handy to have a list of colors with the HTML title as "Colors in Pyret" or something else more meaningful to a student than "3.18?image-structs", which is what currently comes up in Google Classroom when I paste in the link.

From bootstrapworld/curr#350

The variable name shown in the contract for order-by is ascending, which is not a valid variable name at all.

All the examples in the docs

https://pyret.org/docs/latest/string-dict.html#%28part._string-dict_.String.Dict_string-dict_set%29

only show updates to existing fields, misleading readers into thinking you can't use this to extend a dictionary. A test like this can help:

check:
  s1 = [string-dict: ]
  s2 = s1.set("Hello", "World")
  s2.get("Hello") is some("World")
end

Thanks to Sam Weiss (CSCI 0190) for pointing this out!

The doc previously said:

A function expression is syntactic sugar for a let and an anonymous function expression.

This is obviously false for recursive functions. So I add "for non-recursive case" to the doc. Still, it is awkward as readers might wonder how recursive functions get desugared. Also, fun in fact always gets desugared to a variable assignment, so it's technically inaccurate too.

Docs say it's there

https://www.pyret.org/docs/latest/image.html#%28part._image_bitmap-url%29

but CPO says it's not.

Tara claims it worked for her a few minutes ago; she brought her laptop down; and said it was no longer working. That's really weird, but also, if it weren't bound at all, I don't know how her code could have worked. Confused.

But setting that aside, there seems to be an inconsistency between docs and code. image-url works fine.

The Google sheet ID used in the example here is not accessible, and causes error No Spreadsheet with id "1BAexzf08Q5o8bXb_k8PwuE3tMKezxRfbKBKT-4L6UzI" found in Pyret.

First off, please feel free to close this issue; I'm partly just interested to know if this is the right way to report things like this, or if things like this should be reported at all.

I've just spent a happy half-hour running through some of the first assignments from csci0111, and in assignment 2 I can't use the link because I don't have a brown gmail address, no problem but I have to figure out how to import the list functions myself. Assignment 1 uses the form "include image" to import the image library.

Trying to use "include lists" fails with a giant list of "please don't re-import " errors. I went looking for "include" in the docs, and I'm pretty sure it's not there at all. I do see the docs for "import", which give me everything I need, but it looks like "include" is undocumented.

Steps to reproduce:

1. visit this URL: https://www.pyret.org/docs/latest/Glossary.html?q=include

The examples are putting x, y before the two images, rather than x, y between the two images , as the contract and implementation expect.

https://pyret.org/docs/latest/image.html#%28part._image_scene-line%29

scene-line :: (
img :: Image,
x1 :: Number,
y1 :: Number,
x2 :: Number,
y2 :: Number,
background :: Image
)
-> Image
Draws a line from (x1,y1) to (x2,y2) on the scene background. Unlike add-line, this function crops the resulting image to be the same size as background.

But the background parameter should instead refer to a parameter of type ImageColor, as seen below for add-line:

https://pyret.org/docs/latest/image.html#%28part._image_add-line%29

add-line :: (
img :: Image,
x1 :: Number,
y1 :: Number,
x2 :: Number,
y2 :: Number,
color :: ImageColor
)
-> Image
Creates a new image like img with a line added starting from the point (x1,y1) and going to the point (x2,y2). Unlike scene-line, if the line passes outside of img, the image gets larger to accommodate the line.

Additionally, scene-line adds a small black border around the resultant image, which is not a stated feature of either scene-line, add-line, or crop.

Nothing for yellow!

https://www.pyret.org/docs/latest/Declarations.html#%28elem._%28bnf-prod._%28.Pyret._let-decl%29%29%29

It currently is:

‹let-decl›: ‹binding› = ‹binop-expr›

I believe it should be:

‹let-decl›: ‹binding› = ‹expr›

@schanzer suggests linking to Bootstrap from the main page (like we do to DCIC), which is a good idea. Just having a full curriculum list would be nice and we can add others as needed.

runtime.runThunk seems to be critical to getting Pyret and Javascript to play nicely together when you want to do asynchronous things, but I can't find it anywhere in the docs.

Possible typo on the following line.

Maybe this should return a mutable string dict?

The current line returns a String Dict (SD-of "a")
@collection-doc["mutable-string-dict" #:contract `(a-arrow ("elt" "a") ,(SD-of "a"))]

I think the correct line would be the following but I may be incorrect!

@collection-doc["mutable-string-dict" #:contract `(a-arrow ("elt" "a") ,(MSD-of "a"))]

Searching for "examples" should give a useful result, but just gives a link to examples of spy:

typo: "imagaginary" is not a word

The only example on the relevant docs page is import equality as EQ (a builtin library).

The my-gdrive and shared-gdrive variants should be documented there as well.

If they are documented elsewhere, I would not know where to look.

... rather than degrees. Currently, no input units are specified.

On the Tables page, under "Extracting Columns from Tables" (currently section 3.22.7), there is the following example:

name-list = select name from my-table end
check:
  name-list is [list: "Bob", "Alice", "Eve"]
end

The "select" in this code example should say "extract" as shown below:

name-list = extract name from my-table end
check:
  name-list is [list: "Bob", "Alice", "Eve"]
end

It's not clear that you can produce monotype font, for example.

Need to add docs for rounding functions in brownplt/pyret-lang#1574

Currently this rule is mentioned in

• ‹app-args› in sec. 2.1.11.4 Application Expressions

  Note that there is no space allowed before the opening parenthesis of the application.
  https://pyret.org/docs/latest/Expressions.html#%28part._s~3aapp-expr%29

• ‹inst-expr› in sec. 2.1.11.7 Instantiation Expressions

  Spaces are not permitted before the left-angle bracket or after the right-angle bracket
  https://pyret.org/docs/latest/Expressions.html#%28part._s~3ainst-expr%29

But Pyret will also complain if a space exists before opening parenthesis in

• function declaration expressions like fun f (n): n end
  https://pyret.org/docs/latest/s_declarations.html#%28part._s~3afun-decl%29
• lambda expressions lam (n): n end
  https://pyret.org/docs/latest/Expressions.html#%28part._s~3alam-expr%29

This also seems to suggest, that the grammar rule for ‹args› (line 916 below)

args: PARENNOSPACE [list-arg-elt* binding] RPAREN

As a reference, in pyret-grammar.bnf in pyret-lang repo, ‹args› has grammar rule

args: (PARENNOSPACE|PARENAFTERBRACE) [binding (COMMA binding)*] RPAREN

https://www.pyret.org/docs/latest/lists.html#%28part._lists_sort-by%29

Missing comparators

https://pyret.org/docs/latest/Expressions.html#%28part._s~3aconstruct-expr%29

type Constructor<A> = {
  make0 :: ( -> A),
  make1 :: (Any -> A),
  make2 :: (Any, Any -> A),
  make3 :: (Any, Any, Any -> A),
  make4 :: (Any, Any, Any, Any -> A),
  make5 :: (Any, Any, Any, Any, Any -> A)
  make  :: (RawArray<Any> -> A),
}

Comma missing on the make5 line.

[Credit: Aren Guralp.]

Personally I’d like to bring them back, but for now their presence in the docs is surely a bug

Right now, the order of the entries on the Builtins and Libraries page (horizon link) makes sense to us as Pyret compiler developers, but it seems counterintuitive. They should be reorganized to either (a) be alphabetized or (b) be partitioned into logical groups which are then individually alphabetized. Regardless, we should pick a convention and stick with it.

Note that even in the case of (a), the Builtins should be kept at the top, with the Libraries beneath them.

@jpolitz @shriram @blerner @anyotherhigherpowersthatbe

We could use a list of the built-in valid for operators in addition to map, filter and fold.

I just wrote one for fold_n (https://code.pyret.org/editor#share=11xDUUtBkp-FtsvXGV3izsA3sOeJhY89U&v=be0f222) for myself and was just going to start on fold2 when I discovered to my surprise that it already works. I couldn't find the relevant code in the Pyret source tree.

The longer explanation of for operators should also be moved from the tour to section 2.1.

The documentation for num-atan is incomplete, and doesn't explain the range of angles that it returns. Then we need to explain num-atan2 and how and why it differs.

Once brownplt/pyret-lang#1134 lands, we'll have a new function take-while available, which takes a predicate and splits a list into a front and back part such that all the items in the front list pass the predicate, and the first item of the back list fails.

Bottom of A Tour of Pyret has a code block demonstrating when, but which is missing a block.

Now that we have a glossary/index, searching seems more feasible. Adding a fuzzy-matching search textbox at the top of this page could go a long way:

https://www.pyret.org/docs/latest/Glossary.html

https://www.pyret.org/docs/latest/Expressions.html#%28part._s~3aconstruct-expr%29
gives an example of the weird constructor.

The test suite shown is actually erroneous in the two-argument case:

There should be results for is-roughly:

Entering "expression forms" in the search bar will instead search for "expression%20forms". We need to deal with the percent encoding properly.

https://pyret.org/docs/latest/tables.html#%28part._.Ordering_.Tables%29

This example will first sort the data in increasing order on column1. If there are any duplicate values in column1, each such group of rows will be sorted in decreasing order by column2. If there are any duplicates in both columns, each remaining group will be sorted in increasing order by column3.

But the order expression is in the order column1, column3, column2. Just swap 3 and 2 in the displayed code.

Thanks to Henry Nieves at Brown for finding this error.