<commit_before># Jet module API doc.

## jet.peer

To access the `jet.peer` module:

```lua
local peer = require('jet.peer')
```

### pi = peer.new([config])

Creates a new peer using Jet's "trivial" message protocol and returns it.
If `config.sync` is not `true` then all methods of `pi` are async/non-blocking.

```lua
local peer = require('jet.peer')
local pi = peer.new()
```

The `config` table is optional. If provided all entries are optional too:

```lua
local pi = peer.new({
  ip = '192.168.1.23', -- the jet daemon ip, default 'localhost'
  port = '192.168.1.23', -- the jet daemon 'trivial' port, default 11122
  name = 'foo', -- some name which will be assoc. at the daemon for debugging
  loop = my_loop, -- an lua-ev loop instance, default ev.Loop.default
  on_connect = print, -- a function which will be called 'on connect' to the daemon
  on_close = print, -- a function which will be called when the peer closes
  sync = false, -- creates sync working peer
})
```

When the `config.sync` flag is set, the peer instance behaves very different than the 'default/async' one.
The 'sync' peer is documented separatly.

### pi:close()

Closes the peer instance. All states, methods and fetchers will be removed from the Jet daemon.

### pi:call(path,[params],[callbacks])

Issues a 'call' Jet message to the daemon with the specified path and parameters. If `callbacks` is provided, the message is a Request and either `callbacks.success` or `callbacks.error` will be called on Response.

```lua
pi:call('persons/create',{name='peter',age=23},{
  success = function(result)
    print('success',result)
  end,
  error = function(err)
    print('failure',err.message,err.code)
  end
})
```

### pi:set(path,value,[callbacks])

Issues a 'set' Jet message to the daemon with the specified path and value. If `callbacks` is provided, the message is a Request and either `callbacks.success` or `callbacks.error` will be called on Response.

```lua
pi:set('persons/ae62a',{name='peter',age=33},{
  success = function()
    print('success')
  end,
  error = function(err)
    print('failure',err.message,err.code)
  end
})
```

### fetcher = pi:fetch(match|fetch_params,fetch_callback,[callbacks])

Creates a new fetcher. If the first parameter is a string, a 'fetch' message whith the following `fetch_params` is send to the daemon:

```lua
fetch_params = {
  matches = {match}
}
```

Else the `fetch_params` are used unmodified. If `fetch_params.sort` is not defined or is no valid sort option, the `fetch_callback` receives the parameters `(event,path,value,fetcher)`. The `event` can be either `add`, `change` or `remove`. `add` is always the first event. `change` means that the paths's associated `value` has changed and `remove` means that the state or method are not available at the Jet bus any longer. States and methods may become available any time later on, though. Note that `value` is `nil` for methods. 

```lua
local allstuff = pi:fetch('.*',function(event,path,value)
  print(event,path,value)
end)
```

Else, if `fetch_params.sort` specifies a valid sort config, the `fetch_callback` receives the parameters `(changes,n)`. To minimize network traffic, only the changes are posted to the peers. `changes` is an array, which contains all entries within the requested sort range (`from`,`to`) which have been changed, added or moved. In addition to their respective `path` and `value` there is also the `index` field, specifying the position within the sort range. `n` denotes the number of elements that are currently in the requested sorted collection. `n` >= 0 and n <= (`to` - `from`). 

```lua
local top_ten = {}

local show_top_ten = function(changes,n)
  -- merge the changes into top_ten
  for _,change in ipairs(changes) do
    top_ten[change.index] = {
		path = change.path,
		value = change.value
	}
  end
  -- display top_ten
  -- note: maybe there are only 5 players available (some may lhave left the game meanwhile)
  -- in this case n is 5.
  for i=1,n do
    print('pos:',i,top_ten[i].path,top_ten[i].value)
  end
end

pi:fetch({
    matches = {'player'},
	sort = {
	  byValue = true,    -- optional, default is false
	  descending = true, -- optional, default is false
	  prop = 'score', -- optional, tells which entry of table to use as order criteria
	  from = 1, -- optional, default is 1
	  to = 10, -- optional, default is 10
	}
  },function(changes,n)    
    print(changes,n)
  end)
```

The `fetcher` argument passed in as `fetch_callback` param is the same as returned by the `pi:fetch(...)` call. You can use the `fetcher` to call `fetcher:unfetch()`.

```lua
-- print first 5 events
local i = 0
pi:fetch('.*',function(event,path,value,fetcher)
  print(event,path,value)
  i = i + 1
  if i == 5 then
    fetcher:unfetch()<commit_msg>respect new fetch syntax<commit_after># Jet module API doc.

## jet.peer

To access the `jet.peer` module:

```lua
local peer = require('jet.peer')
```

### pi = peer.new([config])

Creates a new peer using Jet's "trivial" message protocol and returns it.
If `config.sync` is not `true` then all methods of `pi` are async/non-blocking.

```lua
local peer = require('jet.peer')
local pi = peer.new()
```

The `config` table is optional. If provided all entries are optional too:

```lua
local pi = peer.new({
  ip = '192.168.1.23', -- the jet daemon ip, default 'localhost'
  port = '192.168.1.23', -- the jet daemon 'trivial' port, default 11122
  name = 'foo', -- some name which will be assoc. at the daemon for debugging
  loop = my_loop, -- an lua-ev loop instance, default ev.Loop.default
  on_connect = print, -- a function which will be called 'on connect' to the daemon
  on_close = print, -- a function which will be called when the peer closes
  sync = false, -- creates sync working peer
})
```

When the `config.sync` flag is set, the peer instance behaves very different than the 'default/async' one.
The 'sync' peer is documented separatly.

### pi:close()

Closes the peer instance. All states, methods and fetchers will be removed from the Jet daemon.

### pi:call(path,[params],[callbacks])

Issues a 'call' Jet message to the daemon with the specified path and parameters. If `callbacks` is provided, the message is a Request and either `callbacks.success` or `callbacks.error` will be called on Response.

```lua
pi:call('persons/create',{name='peter',age=23},{
  success = function(result)
    print('success',result)
  end,
  error = function(err)
    print('failure',err.message,err.code)
  end
})
```

### pi:set(path,value,[callbacks])

Issues a 'set' Jet message to the daemon with the specified path and value. If `callbacks` is provided, the message is a Request and either `callbacks.success` or `callbacks.error` will be called on Response.

```lua
pi:set('persons/ae62a',{name='peter',age=33},{
  success = function()
    print('success')
  end,
  error = function(err)
    print('failure',err.message,err.code)
  end
})
```

### fetcher = pi:fetch(contains|fetch_params,fetch_callback,[callbacks])

Creates a new fetcher. If the first parameter is a string, a 'fetch' message whith the following `fetch_params` is send to the daemon:

```lua
fetch_params = {
  path = {
    contains = contains
  }
}
```

Else the `fetch_params` are used unmodified. If `fetch_params.sort` is not defined or is no valid sort option, the `fetch_callback` receives the parameters `(event,path,value,fetcher)`. The `event` can be either `add`, `change` or `remove`. `add` is always the first event. `change` means that the paths's associated `value` has changed and `remove` means that the state or method are not available at the Jet bus any longer. States and methods may become available any time later on, though. Note that `value` is `nil` for methods. 

```lua
local allstuff = pi:fetch('.*',function(event,path,value)
  print(event,path,value)
end)
```

Else, if `fetch_params.sort` specifies a valid sort config, the `fetch_callback` receives the parameters `(changes,n)`. To minimize network traffic, only the changes are posted to the peers. `changes` is an array, which contains all entries within the requested sort range (`from`,`to`) which have been changed, added or moved. In addition to their respective `path` and `value` there is also the `index` field, specifying the position within the sort range. `n` denotes the number of elements that are currently in the requested sorted collection. `n` >= 0 and n <= (`to` - `from`). 

```lua
local top_ten = {}

local show_top_ten = function(changes,n)
  -- merge the changes into top_ten
  for _,change in ipairs(changes) do
    top_ten[change.index] = {
		path = change.path,
		value = change.value
	}
  end
  -- display top_ten
  -- note: maybe there are only 5 players available (some may lhave left the game meanwhile)
  -- in this case n is 5.
  for i=1,n do
    print('pos:',i,top_ten[i].path,top_ten[i].value)
  end
end

pi:fetch({
    path = {
		startsWith = 'player'
	},
	sort = {
	  byValueField = {
		  score = 'number',
	  }
	  descending = true, -- optional, default is false
	  from = 1, -- optional, default is 1
	  to = 10, -- optional, default is 10
	}
  },function(changes,n)    
    print(changes,n)
  end)
```

The `fetcher` argument passed in as `fetch_callback` param is the same as returned by the `pi:fetch(...)` call. You can use the `fetcher` to call `fetcher:unfetch()`.

```lua
-- print first 5 events
local i = 0
pi:fetch('.*',function(event,path,value,fetcher)
  print(event,path,value)
  i = i + 1
  if i == 5 then
    fetcher:unfetch()
{'fraction_non_alphanumeric': 0.12338548776646015, 'fraction_numerical': 0.009030767615247296, 'mean_word_length': 4.033826638477802, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, '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': '6727098', 'n_tokens_mistral': 3063, 'n_tokens_neox': 2904, 'n_words': 1194}