Skip to content

Commit

Permalink
Try to express h-value / r-value as a table
Browse files Browse the repository at this point in the history
  • Loading branch information
Andy C committed Dec 31, 2024
1 parent a17ddcf commit f84a65d
Showing 1 changed file with 84 additions and 29 deletions.
113 changes: 84 additions & 29 deletions doc/ref/chap-word-lang.md
Original file line number Diff line number Diff line change
Expand Up @@ -300,34 +300,89 @@ string:

---

`${x@a}` returns the set of characters that represent the attributes of
*h-value* of the expansion `$x`.
`${x@a}` returns characters that represent the attributes of the `${x}`, or
more precisely, the *h-value* of `${x}`.

Definitions:

- *h-value* is the variable (or the object that the variable directly points)
from which the result of `${x}` would originally come.
- *r-value* is the expansion of `${x}`

For example, with `arr=(1 2 3)`:

<style>
table {
width: 100%;
margin-left: 2em; /* matches p text in manual.css */
}
thead {
text-align: left;
}
</style>

<table>

- thead
- Reference
- Expression
- H-value
- R-value
- Flags returned
- tr
- <!-- empty -->
- `${arr[0]@a}` or <br/> `${arr@a}`
- array<br/> `(1 2 3)`
- string<br/> `1`
- `a`
- tr
- <!-- empty -->
- `${arr[@]@a}`
- array<br/> `(1 2 3)`
- array<br/> `(1 2 3)`
- `a a a`
- tr
- `ref=arr` or `ref=arr[0]`
- `${!ref@a}`
- array<br/> `(1 2 3)`
- string<br/> `1`
- `a`
- <!-- empty -->
- tr
- `ref=arr[@]`
- `${!ref@a}`
- array<br/> `(1 2 3)`
- array<br/> `(1 2 3)`
- `a a a`

</table>

When `${x}` would result in a word list, `${x@a}` returns a word list
containing the attributes of the *h-value* of each word.

Here, *h-value* is the variable (or the object that the variable directly
points) from which the result of `$x` would originally come. This is different
from the *r-value* of the expansion `$x`, namely the result of the expansion
`$x`.

The characters representing attributes are listed below:

- `a`: The value of `$x` would be obtained from an indexed array element.
- `A`: The value of `$x` would be obtained from an associative array element.
- `r`: The value of `$x` would be obtained from a readonly container.
- `x`: The value of `$x` would be obtained from a container with the export attribute.
- `n`: `x` is a name reference (OSH extension)

It should be noted that `${x@a}` does not return the attributes of the
*r-value* of the expansion `$x`. For example, although the *r-value* of
`${arr[0]}` is arr scalar string, `${arr[0]@a}` returns `a` because the
*h-value* is array `arr`, which stores the element `arr[0]`.

$ echo ${arr[0]@a}
a

When `$x` would result in a word list (such as `${arr[@]}` and `${!ref}` with
`ref="arr[@]"`), `${x@a}` returns a word list containing the attributes of the
*h-value* of each word.
---

$ arr=(1 2 3)
$ echo "${arr[@]@a}"
a a a
These characters may be returned:

<table>

- thead
- Character
- Where `${x}` would be obtained
- tr
- `a`
- indexed array
- tr
- `A`
- associative array
- tr
- `r`
- readonly container
- tr
- `x`
- exported variable
- tr
- `n`
- name reference (OSH extension)

</table>

0 comments on commit f84a65d

Please sign in to comment.