<commit_before>+++
title = "Examples"
weight = 7
template = "doc.html"
+++

# Contents

- [Introduction](#introduction)
- [%warp](#warp) - Read and Subscribe.
   - [%sing](#sing) - Read a file or directory.
   - [%next](#next) - Subscribe for the next change to a file or directory.
   - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
   - [%many](#many) - Track changes to a `desk` for the specified range of revisions.
   - [Cancel Subscription](#cancel-subscription)
- [%info](#info) - Write and Modify.
   - [%ins](#ins) - Add a file.
   - [%del](#del) - Delete a file.
   - [%mut](#mut) - Change a file.
   - [Multiple Changes](#multiple-changes) - Change multiple files.
- [Manage Mounts](#manage-mounts)
   - [%boat](#boat) - List mounts.
   - [%mont](#mont) - Mount something.
   - [%ogre](#ogre) - Unmount something.
   - [%dirk](#dirk) - Commit changes.
- [Merge Desks](#merge-desks)
   - [%merg](#merg)
- [Permissions](#permissions)
   - [%perm](#perm) - Set file permissions.
   - [%cred](#cred) - Add permission group.
   - [%crew](#crew) - Get permission groups.
   - [%crow](#crow) - Get group usage.
- [Foreign Ships](#foreign-ships)
   - [%warp](#warp-remote) - Read a file on a foreign ship.
   - [%merg](#merg-remote) - Merge from a foreign `desk`.

# Introduction

This document contains a number of examples of interacting with Clay using its various `task`s. Sections correspond to the general details in the [API Reference](@/docs/arvo/clay/tasks.md) document.

Most examples will either use `|pass` to just send a `task` or the following thread to send a `task` and take the resulting `gift`. You can save the following thread to the `ted` directory of your `%home` `desk`:

`send-task-take-gift.hoon`

```hoon
/-  spider
/+  strandio
=,  strand=strand:spider
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
=/  uarg  !<  (unit task:clay)  arg
?~  uarg
  (strand-fail:strand %no-arg ~)
=/  =task:clay  u.uarg
=/  =card:agent:gall  [%pass /foo %arvo %c task]
;<  ~  bind:m  (send-raw-card:strandio card)
;<  res=[wire sign-arvo]  bind:m  take-sign-arvo:strandio
~&  +>:res
(pure:m !>(~))
```

# `%warp`

See the [Read and Subscribe](@/docs/arvo/clay/tasks.md#warp) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.

## `%sing`

Here we'll look at reading files by passing Clay a `%warp` `task` with a `%sing` `rave` and receiving a `%writ` `gift` containing the data in response.


Using the `send-task-take-gift.hoon` thread, let's try reading `gen/hood/hi.hoon`:

```
> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
```

You should see something like this as the output:

```
[ %writ
    p
  [ ~
    [ p=[p=%x q=[%da p=~2021.5.20..23.37.50..e79b] r=%home]
      q=/gen/hood/hi/hoon
        r
      [ p=%hoon
          q
        [ #t/@
            q
          3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
        ]
      ]
    ]
  ]
]
```

The `cage` in the `riot` of the `%writ` contains the file's data due to our use of an `%x` `care`. It needn't be `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:

```
> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
[ %writ
    p
  [ ~
    [ p=[p=%u q=[%da p=~2021.5.20..23.42.21..bb33] r=%home]
      q=/gen/hood/hi/hoon
      r=[p=%flag q=[#t/?(%.y %.n) q=0]]
    ]
  ]
]
```

Here's a breakdown of the `task` we sent:

![%sing diagram](https://media.urbit.org/docs/arvo/clay/sing.png "%sing diagram")

## `%next`

Here we'll look at subscribing to the next version of a file by passing Clay a `%warp` `task` with a `%next` `rave` and receiving a `%writ` `gift` when the file changes.

Using the `send-task-take-gift.hoon` thread, let's subscribe to the next version of `foo.txt`:

```
> -send-task-take-gift [%warp our %home ~ %next %x da+now /foo/txt]
```

Now, in unix, create a file called `foo.txt` in the root of the `home` directory of your ship. In the dojo, hit backspace to disconnect the thread from the dojo prompt and run `|commit %home`. You should see something like:

```
> |commit %home
>=
[%writ p=[~ [p=[p=%x q=[%ud p=3] r=%home] q=/foo/txt r=[p=%txt q=[#t/*'' q=0]]]]]
+ /~zod/home/3/foo/txt
```

As you can see, the `riot` in the `%writ` includes a `cage` with the data of `/foo/txt` due to our use of an `%x` `care`.

Now run the thread again, and this time delete the file in unix and again `|commit %home` in the dojo. You should see:

```
> |commit %home
>=
[%writ p=~]
- /~zod/home/4/foo/txt
```

You can see the `riot` is just `~` due to the file being deleted. 

Here's a breakdown of the task we sent:

![%next diagram](https://media.urbit.org/docs/arvo/clay/sing.png "%next diagram")

## `%mult`
<commit_msg>fix image link<commit_after>+++
title = "Examples"
weight = 7
template = "doc.html"
+++

# Contents

- [Introduction](#introduction)
- [%warp](#warp) - Read and Subscribe.
   - [%sing](#sing) - Read a file or directory.
   - [%next](#next) - Subscribe for the next change to a file or directory.
   - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
   - [%many](#many) - Track changes to a `desk` for the specified range of revisions.
   - [Cancel Subscription](#cancel-subscription)
- [%info](#info) - Write and Modify.
   - [%ins](#ins) - Add a file.
   - [%del](#del) - Delete a file.
   - [%mut](#mut) - Change a file.
   - [Multiple Changes](#multiple-changes) - Change multiple files.
- [Manage Mounts](#manage-mounts)
   - [%boat](#boat) - List mounts.
   - [%mont](#mont) - Mount something.
   - [%ogre](#ogre) - Unmount something.
   - [%dirk](#dirk) - Commit changes.
- [Merge Desks](#merge-desks)
   - [%merg](#merg)
- [Permissions](#permissions)
   - [%perm](#perm) - Set file permissions.
   - [%cred](#cred) - Add permission group.
   - [%crew](#crew) - Get permission groups.
   - [%crow](#crow) - Get group usage.
- [Foreign Ships](#foreign-ships)
   - [%warp](#warp-remote) - Read a file on a foreign ship.
   - [%merg](#merg-remote) - Merge from a foreign `desk`.

# Introduction

This document contains a number of examples of interacting with Clay using its various `task`s. Sections correspond to the general details in the [API Reference](@/docs/arvo/clay/tasks.md) document.

Most examples will either use `|pass` to just send a `task` or the following thread to send a `task` and take the resulting `gift`. You can save the following thread to the `ted` directory of your `%home` `desk`:

`send-task-take-gift.hoon`

```hoon
/-  spider
/+  strandio
=,  strand=strand:spider
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
=/  uarg  !<  (unit task:clay)  arg
?~  uarg
  (strand-fail:strand %no-arg ~)
=/  =task:clay  u.uarg
=/  =card:agent:gall  [%pass /foo %arvo %c task]
;<  ~  bind:m  (send-raw-card:strandio card)
;<  res=[wire sign-arvo]  bind:m  take-sign-arvo:strandio
~&  +>:res
(pure:m !>(~))
```

# `%warp`

See the [Read and Subscribe](@/docs/arvo/clay/tasks.md#warp) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.

## `%sing`

Here we'll look at reading files by passing Clay a `%warp` `task` with a `%sing` `rave` and receiving a `%writ` `gift` containing the data in response.


Using the `send-task-take-gift.hoon` thread, let's try reading `gen/hood/hi.hoon`:

```
> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
```

You should see something like this as the output:

```
[ %writ
    p
  [ ~
    [ p=[p=%x q=[%da p=~2021.5.20..23.37.50..e79b] r=%home]
      q=/gen/hood/hi/hoon
        r
      [ p=%hoon
          q
        [ #t/@
            q
          3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
        ]
      ]
    ]
  ]
]
```

The `cage` in the `riot` of the `%writ` contains the file's data due to our use of an `%x` `care`. It needn't be `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:

```
> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
[ %writ
    p
  [ ~
    [ p=[p=%u q=[%da p=~2021.5.20..23.42.21..bb33] r=%home]
      q=/gen/hood/hi/hoon
      r=[p=%flag q=[#t/?(%.y %.n) q=0]]
    ]
  ]
]
```

Here's a breakdown of the `task` we sent:

![%sing diagram](https://media.urbit.org/docs/arvo/clay/sing.png "%sing diagram")

## `%next`

Here we'll look at subscribing to the next version of a file by passing Clay a `%warp` `task` with a `%next` `rave` and receiving a `%writ` `gift` when the file changes.

Using the `send-task-take-gift.hoon` thread, let's subscribe to the next version of `foo.txt`:

```
> -send-task-take-gift [%warp our %home ~ %next %x da+now /foo/txt]
```

Now, in unix, create a file called `foo.txt` in the root of the `home` directory of your ship. In the dojo, hit backspace to disconnect the thread from the dojo prompt and run `|commit %home`. You should see something like:

```
> |commit %home
>=
[%writ p=[~ [p=[p=%x q=[%ud p=3] r=%home] q=/foo/txt r=[p=%txt q=[#t/*'' q=0]]]]]
+ /~zod/home/3/foo/txt
```

As you can see, the `riot` in the `%writ` includes a `cage` with the data of `/foo/txt` due to our use of an `%x` `care`.

Now run the thread again, and this time delete the file in unix and again `|commit %home` in the dojo. You should see:

```
> |commit %home
>=
[%writ p=~]
- /~zod/home/4/foo/txt
```

You can see the `riot` is just `~` due to the file being deleted. 

Here's a breakdown of the task we sent:

![%next diagram](https://media.urbit.org/docs/arvo/clay/next.png "%next diagram")

## `%mult`

{'fraction_non_alphanumeric': 0.1867704280155642, 'fraction_numerical': 0.0816171585840372, 'mean_word_length': 3.134170262848176, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 21, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3354270', 'n_tokens_mistral': 4809, 'n_tokens_neox': 4088, 'n_words': 1124}