Skip to content

path.adoc

Latest commit

 

History

History
198 lines (138 loc) · 4.33 KB

path.adoc

File metadata and controls

198 lines (138 loc) · 4.33 KB
Raw

Path! datatype

Table of Contents

1. Abstract

The path! datatype represents a series of values delimited by slashes (/). Path! is a type of block! that is limited in the types of values that it can contain. Word!, integer!, get-word!, and paren! values are supported.

Path! is a member of the following typesets: any-block!, any-path!, series!

1.1. Path Variations

Syntax

Datatype

Testing Values

Conversion

foo/bar

path!

path?

to path!

foo/bar:

set-path!

set-path?

to set-path!

:foo/bar

get-path!

get-path?

to get-path!

'foo/bar

lit-path!

lit-path?

to lit-path!

2. Creation

Path values can be created using literal syntax, or at runtime by using a make constructor or to conversion.

>> 'foo/bar/baz
== foo/bar/baz
>> make path! [foo bar baz]
== foo/bar/baz

You can create an empty path of a given size by supplying an integer value as an argument to make:

>> make path! 10
==

To conversion:

>> to path! "foo bar baz"
== foo/bar/baz
Caution
 It is possible to create path! values programmatically that do not conform to the lexical rules of a literal path. 
>> mold to path! [a #[b: 2] c 1.2 /z]
== "a/#(^/    b: 2^/)/c/1.2//z"

>> load mold to path! [a #[b: 2] c 1.2 /z]
*** Syntax Error: invalid path! at "a/#(    b: 2)/c/1.2//z"
*** Where: do
*** Stack: load

3. Literal syntax

BNF:

<path-literal> ::= <path-head>/<selector>
<path-head>    ::= <word-literal> | <path-literal>
<selector> ::= <integer> | <word-literal> | :<word-literal> | <paren>

Parse:

path: [word! some selector]
selector: [#"/" [integer! | word! | get-word! | paren!]]

Path-head datatypes: word!, path!

Selector datatypes: integer!, word!, get-word!, paren!

4. Evaluation Steps

Paths lead to a nested value, or to a more specific behavior in a function call. They must start with a word, and the value that the word refers to determines how the path will be evaluated.

  • If the value is a function, the following expressions in the path must be word! values. These words are treated as refinements in the function call.

>> append/only [42][foo]
== [42 [foo]]

An error will be raised if no corresponding refinement exists in the function:

>> append/xyz [42][foo]
*** Script Error: append has no refinement called xyz
*** Where: append
*** Stack:
Note
 Paths are an active type and will evaluate stored functions. Op! values are not currently evaluated. 
>> f: does [42]
== func [][42]

>> insert b: [] :f
== []

>> b/1
== 42

  • If the value is not a function, the following rules apply:

    • If the next expression in the path is a word, it is used to select from the path-head value. The path-head value must be of a type that supports select (e.g. a block!, map!, or object!).

>> blk: [foo bar baz]
== [foo bar baz]

>> blk/bar
== baz

If the selection does not exist in the path-head value, select will return none:

>> blk/sheboygan
== none

  • Word! expressions in paths, after the first, are not evaluated. If you want to evaluate them, use get-word! or paren! in the path.

>> selector: 'bar
== bar

>> my-block: [foo bar baz]
== [foo bar baz]

>> my-block/:selector
== baz
>> my-block/('bar)
== baz

  • If the next expression in the path is an integer, it is used to pick from the path-head value. The path-head value must be of a type that supports pick (e.g. a series!, tuple!, or date!).

>> blk: [foo bar baz qux]
== [foo bar baz qux]

>> blk/3  ; pick from the third index of blk
== baz

If the integer falls outside the bounds of the path-head value, pick returns none:

>> length? blk
== 4

>> blk/7
== none

>> blk/-1
== none

5. Testing values

Use path? to check if a value is of the path! datatype.

>> path? 'foo/bar
== true

Use type? to return the datatype of a given value.

>> type? 'foo/bar
== path!

6. Predefined words

6.1. Functions

any-block?, any-path?, path?, series?, to-path