REBOL 3 Datatypes: Path!

Contents

Concept

Paths are a collection of words and values delineated with forward slashes (/). Paths are used to navigate to or find something.

Paths can be used on series, maps, functions, and objects. How a path operates depends on the datatype being used. Thus aths can be used to select values from blocks, pick characters from strings, access variables in objects, refine the operation of a function:

USA/CA/Ukiah/size (block selection)

names/12          (string position)

account/balance   (object function)

match/any         (function option)

The example below shows the simplicity of using a path to access a mini-database created from a few blocks:

towns: [
    Hopland [
        phone #555-1234
        web   http://www.hopland.ca.gov
    ]

    Ukiah [
        phone #555-4321
        web   http://www.ukiah.com
        email info@ukiah.com
    ]
]

print towns/ukiah/web
http://www.ukiah.com

Summary of path constructs:

Action	Type Word	Type Test	Conversion
root/word:	set-path!	set-path?	to-set-path
:root/word	get-path!	get-path?	to-get-path
root/word	path!	path?	to-path
'root/word	lit-path!	lit-path?	to-lit-path

Examples of paths:

Evaluate an object's function:

obj: make object! [
    hello: func [] [print "hello! hello!"]
]
obj/hello
hello! hello!

Evaluate an object's word:

obj: make object! [
    text: "do you believe in magic?"
]
probe obj/text
do you believe in magic?

Function refinements:

hello: func [/again] [
    print either again ["hello again!"]["hello"]
]
hello/again
hello again!

Select from blocks, or multiple blocks:

USA: [
    CA [
        Ukiah [
            population 15050
            elevation [610 feet]
        ]
        Willits [
            population 5073
            elevation [1350 feet]
        ]
    ]
]

print USA/CA/Ukiah/population
15050

print form USA/CA/Willits/elevation
1350 feet

Pick elements from series and embedded series by their numeric position:

string-series: "abcdefg"
block-series: ["John" 21 "Jake" 32 "Jackson" 43 "Joe" 52]
block-with-sub-series: [ "abc" [4 5 6 [7 8 9]]]

probe string-series/4
#"d"

probe block-series/3
Jake

probe block-series/6
43

probe block-with-sub-series/1/2
#"b"

probe block-with-sub-series/2/2
5

probe block-with-sub-series/2/4/2
8

The words supplied as path selectors are symbolic and therefore unevaluated. This is necessary to allow the most intuitive form for object referencing. To use a word's reference, an explicit word value reference is required:

city: 'Ukiah
probe USA/CA/:city
[
    population 15050
    elevation "610 feet"
]

Paths in blocks, maps and objects are evaluated by matching the word at the top level of the path, and verifying the word as a [bad-link:datatypes/series.txt], map! or object! value. Then the next value in the path is sought and an implicit select is performed. The value following the matched value is returned. When the returned value is a block, map, or object, the path can be extended:

Getting the value associated with CA in USA:

probe USA/CA
[
    Ukiah [
        population 15050
        elevation "610 feet"
    ]
    Willits [
        population 9935
        elevation "1350 feet"
    ]
]

Getting the value associated with Willits in USA/CA:

probe USA/CA/Willits
[
    population 9935
    elevation "1350 feet"
]

Getting the value associated with population in USA/CA/Willits:

probe USA/CA/Willits/population
9935

When a value is used in a path that does not exist at the given point in the structure, an error is produced:

probe USA/CA/Mendocino
** Script Error: Invalid path value: Mendocino.
** Where: probe USA/CA/Mendocino

Paths can be used to change values in series, maps and objects:

USA/CA/Willits/elevation: "1 foot, after the earthquake"
probe USA/CA/Willits
[
    population 9935
    elevation "1 foot, after the earthquake"
]

obj/text: "yes, I do believe in magic."
probe obj
make object! [
    text: "yes, I do believe in magic."
]

Series, functions, and objects can be mixed in paths.

Selecting from elements in a block inside an object:

obj: make object! [
    USA: [
        CA [
            population "too many"
        ]
    ]
]
probe obj/USA/CA/population
too many

Using function refinements within an object:

obj: make object! [
    hello: func [/again] [
        print either again [
            "hello again"
        ] [
            "oh, hello"
        ]
    ]
]
obj/hello/again
hello again

Paths are themselves type of series, thus anything that can be done with a series can be done with path values:

root: [sub1 [sub2 [
    word "a word at the end of the path"
    num 55
]   ]   ]
path: 'root/sub1/sub2/word
probe :path
root/sub1/sub2/word

In the previous example, the :path notation was used to get the path itself, not the path's value:

probe path
a word at the end of the path

Looking at how long a path is:

probe length? :path
4

Finding a word within a path:

probe find :path 'sub2
sub2/word

Changing a word in a path:

change find :path 'word 'num
probe :path
root/sub1/sub2/num

probe path
55

Format

Paths are expressed relative to a root word by providing a number of selection expressions, each separated by a forward slash (/). These expressions can be words or values. Their specific interpretation vary depending on the datatype of the root value.

The words supplied as selection expressions in paths are symbolic and are not evaluated. This is necessary to allow the most intuitive form for object referencing. To use a word's reference, an explicit word value reference is required:

root/:word

This example uses the value of the variable, rather than it name.

Creation

You can make an empty path of a given size with:

path: make path! 10
insert :path 'test
insert tail :path 'this
print :path
test/this

The to-path function converts data to the path! datatype:

probe to-path [root sub]
root/sub

probe to-path "root sub"
root/sub

The to-set-path function converts other values to the set-word! datatype.

probe to-set-path "root sub"
root/sub:

The to-get-path function converts other values to the set-word! datatype.

probe to-get-path "root sub"
:root/sub

The to-lit-path function converts other values to the lit-word! datatype.

probe to-lit-path "root sub"
'root/sub

Related

Use path?, set-path?, get-path?, and lit-path? to determine the datatype of a value.

probe path? second [1 two "3"]
false

blk: [sub1 [sub2 [word 1]]]
blk2: [blk/sub1/sub2/word: 2]
if set-path? (pick blk2 1) [print "it is set"]
it is set

probe lit-path? first ['root/sub]
true

As paths are a subset of the series! typeset, use series? to check this:

probe series? pick [root/sub] 1
true

Use form on a path value creates a string from the path:

probe form pick [root/sub] 1
root/sub

Use mold on a path value creates a string of the path value itself, thus allowing it to be reloaded as a REBOL path value:

probe mold pick [root/sub] 1
root/sub