~andyc/oil

1d197eae6cf8e29fd11004853a4fa005cd97fb90 — Andy Chu a month ago bd2b071
[doc] Document char literals; update Oil vs. Python

Still need to implement \u{3bc}.

Also:

- Doc automation
- Update Toil home page
4 files changed, 105 insertions(+), 59 deletions(-)

M build/doc.sh
M doc/oil-language-tour.md
M doc/oil-vs-python.md
M services/travis.sh
M build/doc.sh => build/doc.sh +16 -0
@@ 329,6 329,8 @@ help-cards() {
}

tour() {
  ### Build the Oil Language Tour and execute code

  split-and-render doc/oil-language-tour.md

  # Check that the code runs


@@ 357,6 359,20 @@ EOF
  fi
}

one() {
  ### Iterate on one doc quickly

  local doc=${1:-doc/oil-vs-python.md}

  split-and-render $doc

  if test -d ~/vm-shared; then
    local out="${doc%.md}.html"
    local path=_release/VERSION/$out
    cp -v $path ~/vm-shared/$path
  fi
}

make-dirs() {
  mkdir -p $TMP_DIR $CODE_BLOCK_DIR $TEXT_DIR $HTML_DIR/doc
}

M doc/oil-language-tour.md => doc/oil-language-tour.md +11 -6
@@ 611,14 611,19 @@ There are many ways to write integers:
    var hex, octal, binary = 0x0001_0000, 0o755, 0b0001_0101
    echo "$hex $octal $binary"           # => 65536 493 21

<!--
TODO: Implement char literals
There are three ways to write characters, but they're actually **integers**:

Character literals can appear outside of strings, and are actually integers:
    # Pound char literal
    const a = #'A'

    #var newline, mu, a = \n, \u3bc, #'a'
    #echo "$newline $mu $a"
-->
    # Backslash char literals
    const newline = \n  # no quotes because it's a char/int, not a string
    const backslash = \\  # ditto

    # Unicode char literals
    #const mu = \u{3bc}

    echo "chars $a $newline $backslash"  # => chars 65 10 92

#### Float


M doc/oil-vs-python.md => doc/oil-vs-python.md +73 -46
@@ 18,75 18,95 @@ Language](oil-language-tour.html).

## Literals for Data Types

- String literals are like **shell** string literals, not like Python.
  - Single quoted - `r'c:\Program Files\'` or `$'line\n'`.
  - Double Quoted
  - Unicode literals are `\u{3bc}` instead of `\u03bc` and `\U000003bc`
- Dicts: come from JavaScript, with unquoted keys, and "punning".
- Lists: In addition to Python-like literals `['pea', 'nut']`, there are
  shell-like literals `%(pea nut)`.
- Booleans / null: `true`, `false`, and `null` are preferred, but `True`,
  `False`, and `None` are accepted for compatibility.
- Tuples (TODO): Does Oil have true tuples?
  - Singleton tuples like `42,` are disallowed, in favor of the more explicit
    `tup(42)`.
### Same as Python

Other literals like ints and floats are the same as in Python.
- Integers: `123`, `1_000_000`, `0b1100_0010`, `0o755`, `0xff`
- Floats: `1.023e6` (not in V1 of Oil)
- Lists: `['pea', 'nut']`

### New Literal Syntax
### Changed

- Booleans and null: `true`, `false`, and `null` are preferred, but `True`,
  `False`, and `None` are accepted for compatibility.
- String literals are like **shell** string literals, not like Python.
  - Double Quoted: `"hello $name"`
  - Single quoted: `r'c:\Program Files\'` 
  - C-style: `$'line\n'`.
    - Unicode literals are `\u{3bc}` instead of `\u03bc` and `\U000003bc`
- Dicts: use **JavaScript** syntax, not Python
  - Unquoted keys: `{age: 42}`
  - Bracketed keys: `{[myvar + 1]: 'value'}
  - "Punning": `{age}`

### New

- Character literals are **integers**
  - Unicode `\u{03bc}`
  - Backslash: `\n`  `\\`  `\'`
  - Pound `#'a'`
- `%symbol` (used in eggex now, but could also be used as interned strings)
- Raw character literals like `\n` and `\u{03bc}`, and also `#'a'`
- Shell-like list literals: `%(pea nut)` is equivalent to `['pea', 'nut']`
- Unevaluated expressions
  - Block `^(ls | wc -l)`
  - Unevaluated expression: `^[1 + a[i] + f(x)]`
  - Arg list: `^{42, verbose = true}`

## Operators

Kinds of of operators:
### Removed

- Equality `=== ~== in  not in`
- Comparison `< > <= =>`
- Arithmetic `+ -`
- Bitwise `& |`
- Logical `and or`
- Ternary
- Indexing and Slicing
- Function Call
- Other: `++`
- Oil sigils: `$` and `@`
- No tuple type for now.  We might want Go-like multiple return values.

Equality:
<!--
- Tuples (TODO): Does Oil have true tuples?
  - Singleton tuples like `42,` are disallowed, in favor of the more explicit
    `tup(42)`.
-->

- `===` for exact quality?
- `~==` for approximate (numbers and strings)
  - maybe there is no `==`?
## Operators

Oil doesn't overload operators as much, and does string <-> int conversion:
### Same as Python

- `a + b` is for addition, while `a ++ b` is for concatenation.
- `a < b` does numeric comparison (with conversion).  `cmp()` could be for
  strings.
- Arithmetic `+ - * / **`
- Comparison `< > <= =>`
- Bitwise `& | ~ ^`
- Logical `and or not`
- Ternary `0 if true else 1`
- Indexing: `s[i]` evaluates to an integer?
- Slicing: `s[i:j]` evaluates to a string
- Equality `== != in  not in`
- Function Call: `f(x, y)`
  - What about splat `*` and `**`?

Other:
### Changed

- I removed the `1:5:2` syntax because `0::2` conflicts with `module::name`.
  This might have been unnecessary.
- String Concenation: `++` (not `+`, which is always addition)

### New Operators
### New

- Regex match: `s ~ /d+/`
- Glob match `s ~~ '*.py'`
- Approximate Equality `42 ~== '42'`
- Oil sigils: `$` and `@`
- `mydict->key` as an alias for `mydict['key']`
- `++` mentioned above
- Pattern Matching
  - Egg expressions and the `~` operator rather than the `re` module.
  - The `~~` glob match operator

### Not Supported
### Removed

- I removed slice step syntax `1:5:2` because `0::2` conflicts with
  `module::name`.  This was only necessary for Tea, not Oil.
- No string formatting with `%`.  Use `${x %.3f}` instead.
- No `@` for matrix multiply.

<!--
Do we need `is` and `is not` for identity?
-->

### Notes

Oil doesn't overload operators as much, and does string <-> int conversion:

- `a + b` is for addition, while `a ++ b` is for concatenation.
- `a < b` does numeric comparison (with conversion).  `cmp()` could be for
  strings.

## Semantic Differences

- Iterating over a string yields code points, not one-character strings.


@@ 94,7 114,7 @@ Other:
  - TODO: maybe this should be `runeAt()` and `byteAt()`?
- No "accidentally quadratic"
  - No `in` for array/list membership.  Only dict membership.
  - The `++=` operator on strings doesn't exist
  - The `++=` operator on strings doesn't exist.
- Bools and integers are totally separate types.  Oil is like JavaScript, where
  they aren't equal: `true !== 1`.  In Python, they are equal: `True == 1`.



@@ 102,3 122,10 @@ Other:

- [Issue 835: Make expression language compatible with Python](https://github.com/oilshell/oil/issues/835)

## TODO

- Test out `%symbol`
- `100 MiB`?  This should be multiplication?
- All the unevaluated expressions



M services/travis.sh => services/travis.sh +5 -7
@@ 103,21 103,19 @@ home-page() {

    <h1>travis-ci.oilshell.org</h1>

    <p>This server receives build results from 
       <a href="https://travis-ci.org/oilshell/oil">travis-ci.org/oilshell/oil</a>.
       See
       <a href="https://github.com/oilshell/oil/wiki/Travis-CI-for-Oil">Travis CI for Oil</a> for details.
    <p>This server receives results from cloud build services.
       See <a href="https://github.com/oilshell/oil/wiki/Toil">Toil</a> for details.
    </p>

    <ul>
      <li>
        <a href="srht-jobs/">sr.ht Jobs</a>
        <a href="srht-jobs/">sr.ht Jobs</a> from <a href="https://builds.sr.ht/~andyc">builds.sr.ht/~andyc</a>
      </li>
      <li>
        <a href="github-jobs/">Github Actions Jobs</a>
        <a href="github-jobs/">Github Actions Jobs</a> from <a href="https://github.com/oilshell/oil/actions/workflows/all-builds.yml">github.com/oilshell/oil/actions/workflows/all-builds.yml</a>
      </li>
      <li>
        <a href="travis-jobs/">Travis Jobs</a>
        <a href="travis-jobs/">Travis Jobs</a> from <a href="https://app.travis-ci.com/github/oilshell/oil">app.travis-ci.com/oilshell/oil</a>
      </li>
      <li>
        <a href="builds/">Builds</a> (not yet implemented)