
-- general --

device:
	file:	data storage device
			block device or sequential
			rw pointer movable

	dir:	special block device, read-only
			reading yields a list

	link:	special block device

	pipe:	special sequential device
			read-only or write-only

	tty:	special sequential device
			read-write
			movable (x,y) write pointer

	socket:	special sequential device
			read-write


path:		"relative/path"				((caveat: amiguous with protocol specifier))
			"./relative/path"
			"../relative/path"
			"~/path"
			"/absolute/aka/hard/path"
			"/"


url:		"path"						--> implies protocol "file"
			"protocol:/hard/path"
			"protocol:///hard/path"
			"protocol://host/hard/path"
			"protocol:[//[[user[:pw]@]host[:port]]]/hard/path"


protocol:	file, ftp, http, scp, tcp, udp, mail, smtp, ...


symbolic links:
			symbolic links are always followed
			except for device "link", which does not follow the last path component


-- words --


instruction cd:

	cd "path"					device = dir


instruction pwd:

	pwd		--> prints realpath of working directory
			==  realpath "."


instruction dir:

	dir "url[/mask]"			device = dir
								print beautified directory listing
								if path does not lead to a directory device,
								then the last path component is handled as a mask


instruction [new] device|var:

	[new] device  "url" 		[= text]	whether you can't, may, or must store
	[new] device ("url",flags)	[= text]	initial data depends on the type of device
											"new" cannot be omitted for device "dir"

	[[new][var]] var.ref    = number | text | list | proc
	[new] proc  var.ref() { ... }


instruction del device|var:

	del device "url"	delete file, pipe, empty directory, etc.
						device must match actual device found at "path"
	del [var] var.ref
	del       *


instruction var_ref device|var:

	name device "url" = "newname" | "new/path"
						rename and optionally move device to other directory
						the actual device type is not checked; use "file" or "link"
	name [var] var.ref = "newname"


instruction swap device|var:

	swap device "url" , [device2] "path2"
						you can only swap devices on the same host and hard device
						both devices should be the same type
						but sometimes you can also swap different types, e.g. dir and file
						actual device types are not checked; use "file" or "link"
	swap [var] var.ref, [var] var.ref2


instruction open[|in|out] serialdevice:

	open    [#number,]	[device] "url"		if device is omitted, then "file" is assumed
	openin  [#number,]	[device] "url"
	openout [#number,]	[device] "url"

	open    [#number,]	device("url",flags)
	openin  [#number,]	device("url",flags)
	openout [#number,]	device("url",flags)


instruction freeze|melt file|var:

	freeze file "url"
	freeze [var] text.var.ref

	melt file "url"
	melt [var] text.var.ref


function realpath device:

	text   = realpath [device] "url"
						final symbolic link is followed except for device "link"
						does not set error if path components do not exist
						does not check the actual device at the path position
						returned path ends on "/" if fileprot==dir or path=="/"


function exists device|var:

	bool   = exists device "url"
						returns true if device exists AND is of requested type
	bool   = exists [var] var.ref


function typeof device|var:

	text = typeof device "url"
	text = typeof value

	return values:
		"number", "text", "list", "proc"
		"file", "dir", "pipe", "link", "socket", "unknown", "free"  <-- match device names!


function isfile, isdir, islink device:

	bool   = isfile "url"
	bool   = isdir  "url"
	bool   = islink "url"


function count blockdevice|var:

	number = count device "url"				block devices only
	number = count [list|text]


function mdate device:

	number = mdate [device] "url"			default device = "file"


function blockdevice|var:

	text = device "url"
	list = dir "url[/mask]"
	number|text|list|proc = value


function|instruction call url:

			call  [device] "url" [, arguments]		default device = "file"
	value =	call( [device] "url" [, arguments] )


function|instruction sys file:

			sys  [file] "path" [, arguments]		device = "file"
	list =	sys( [file] "path" [, arguments] )

	returned list = { "stdout_data", "stderr_data", return_code }


function|instruction include url | eval var:

			include [device] "url"					default device = "file"
	value =	include [device] "url"

			eval  text
	value = eval  text








