spin 0.5.1 · OCaml Package

include module type of struct include FileUtil end

Types and exceptions

exception FileDoesntExist of FilePath.filename

exception RecursiveLink of FilePath.filename

type 'a error_handler = string -> 'a -> unit

Generic error handling functions. Whenever such a function is available it helps report the error and allows to raise an exception. The string provided is the human readable version of 'a. In most cases 'a is a polymorphic variant.

exception Fatal of string

Exception raised when after an error_handler the execution cannot continue. The rest of the workflow logic cannot handle the default case and the whole operation can be in the middle of transformation.

type action_link = FileUtil.action_link =

| Follow
(*
We consider link as simple directory (it is dangerous)
*)
| Skip
(*
Just skip it
*)
| SkipInform of FilePath.filename -> unit
(*
Skip and execute an action
*)
| AskFollow of FilePath.filename -> bool
(*
Ask and wait for input, false means skip
*)

Policy concerning links which are directories.

type interactive = FileUtil.interactive =

| Force
(*
Do it anyway
*)
| Ask of FilePath.filename -> bool
(*
Promp the user
*)

For certain command, you should need to ask the user wether or not he wants to act.

Permission

type base_permission = FileUtil.base_permission = {

sticky : bool;
exec : bool;
write : bool;
read : bool;

}

Base permission. This is the permission corresponding to one user or group.

type permission = FileUtil.permission = {

user : base_permission;
group : base_permission;
other : base_permission;

}

Full permission. All the base permissions of a file.

val permission_of_int : int -> permission

Translate POSIX integer permission.

val int_of_permission : permission -> int

Return the POSIX integer permission

module Mode = FileUtil.Mode

Permission symbolic mode.

Size operation

type size = FileUtil.size =

| TB of int64
(*
Tera bytes
*)
| GB of int64
(*
Giga bytes
*)
| MB of int64
(*
Mega bytes
*)
| KB of int64
(*
Kilo bytes
*)
| B of int64
(*
Bytes
*)

File size

val byte_of_size : size -> int64

Convert size to bytes.

val size_add : size -> size -> size

Add two sizes.

val size_compare : ?fuzzy:bool -> size -> size -> int

Compare two sizes, using the classical compare function. If fuzzy is set to true, the comparison is done on the most significant size unit of both value.

val string_of_size : ?fuzzy:bool -> size -> string

Convert a value to a string representation. If fuzzy is set to true, only consider the most significant unit

stat

type kind = FileUtil.kind =

| Dir
| File
| Dev_char
| Dev_block
| Fifo
| Socket
| Symlink
(*
- since 0.4.6
*)

Kind of file. This set is a combination of all POSIX file, some of them doesn't exist at all on certain file system or OS.

type stat = FileUtil.stat = {

kind : kind;
is_link : bool;
permission : permission;
size : size;
owner : int;
group_owner : int;
access_time : float;
modification_time : float;
creation_time : float;
device : int;
inode : int;

}

Information about a file. This type is derived from Unix.stat

val stat : ?dereference:bool -> FilePath.filename -> stat

stat fln Return information about the file (like Unix.stat) Non POSIX command.

umask

exception UmaskError of string

type umask_error = [

| `Exc of exn
| `NoStickyBit of int

]

Possible umask errors.

val umask : 
  ?error:umask_error error_handler ->
  ?mode:[< `Octal of int | `Symbolic of Mode.t ] ->
  [< `Octal of int -> 'a | `Symbolic of Mode.t -> 'a ] ->
  'a

Get or set the file mode creation mask. See POSIX documentation.

val umask_apply : int -> int

Apply umask to a given file permission.

test

type test_file = FileUtil.test_file =

| Is_dev_block
(*
FILE is block special
*)
| Is_dev_char
(*
FILE is character special
*)
| Is_dir
(*
FILE is a directory
*)
| Exists
(*
FILE exists
*)
| Is_file
(*
FILE is a regular file
*)
| Is_set_group_ID
(*
FILE is set-group-ID
*)
| Has_sticky_bit
(*
FILE has its sticky bit set
*)
| Is_link
(*
FILE is a symbolic link
*)
| Is_pipe
(*
FILE is a named pipe
*)
| Is_readable
(*
FILE is readable
*)
| Is_writeable
(*
FILE is writeable
*)
| Size_not_null
(*
FILE has a size greater than zero
*)
| Size_bigger_than of size
(*
FILE has a size greater than given size
*)
| Size_smaller_than of size
(*
FILE has a size smaller than given size
*)
| Size_equal_to of size
(*
FILE has the same size as given size
*)
| Size_fuzzy_equal_to of size
(*
FILE has approximatively the same size as given size
*)
| Is_socket
(*
FILE is a socket
*)
| Has_set_user_ID
(*
FILE its set-user-ID bit is set
*)
| Is_exec
(*
FILE is executable
*)
| Is_owned_by_user_ID
(*
FILE is owned by the effective user ID
*)
| Is_owned_by_group_ID
(*
FILE is owned by the effective group ID
*)
| Is_newer_than of FilePath.filename
(*
FILE1 is newer (modification date) than FILE2
*)
| Is_older_than of FilePath.filename
(*
FILE1 is older than FILE2
*)
| Is_newer_than_date of float
(*
FILE is newer than given date
*)
| Is_older_than_date of float
(*
FILE is older than given date
*)
| And of test_file * test_file
(*
Result of TEST1 and TEST2
*)
| Or of test_file * test_file
(*
Result of TEST1 or TEST2
*)
| Not of test_file
(*
Result of not TEST
*)
| Match of string
(*
Compilable match (Str or PCRE or ...)
*)
| True
(*
Always true
*)
| False
(*
Always false
*)
| Has_extension of FilePath.extension
(*
Check extension
*)
| Has_no_extension
(*
Check absence of extension
*)
| Is_parent_dir
(*
Basename is the parent dir
*)
| Is_current_dir
(*
Basename is the current dir
*)
| Basename_is of FilePath.filename
(*
Check the basename
*)
| Dirname_is of FilePath.filename
(*
Check the dirname
*)
| Custom of FilePath.filename -> bool
(*
Custom operation on filename
*)

Pattern you can use to test file. If the file doesn't exist the result is always false.

val test : 
  ?match_compile:(FilePath.filename -> FilePath.filename -> bool) ->
  test_file ->
  FilePath.filename ->
  bool

Test a file. See POSIX documentation.

chmod

exception ChmodError of string

type chmod_error = [

| `Exc of exn

]

Possible chmod errors.

val chmod : 
  ?error:chmod_error error_handler ->
  ?recurse:bool ->
  [< `Octal of Unix.file_perm | `Symbolic of Mode.t ] ->
  FilePath.filename list ->
  unit

Change permissions of files. See POSIX documentation.

mkdir

exception MkdirError of string

type mkdir_error = [

| `DirnameAlreadyUsed of FilePath.filename
| `Exc of exn
| `MissingComponentPath of FilePath.filename
| `MkdirChmod of FilePath.filename * Unix.file_perm * string * chmod_error

]

Possible mkdir errors.

val mkdir : 
  ?error:mkdir_error error_handler ->
  ?parent:bool ->
  ?mode:[< `Octal of Unix.file_perm | `Symbolic of Mode.t ] ->
  FilePath.filename ->
  unit

Create the directory which name is provided. Set ~parent to true if you also want to create every directory of the path. Use mode to provide some specific right. See POSIX documentation.

rm

exception RmError of string

type rm_error = [

| `DirNotEmpty of FilePath.filename
| `Exc of exn
| `NoRecurse of FilePath.filename

]

Possible rm errors.

val rm : 
  ?error:rm_error error_handler ->
  ?force:interactive ->
  ?recurse:bool ->
  FilePath.filename list ->
  unit

Remove the filename provided. Set ~recurse to true in order to completely delete a directory. See POSIX documentation.

cp

exception CpError of string

type cp_error = [

| `CannotChmodDstDir of FilePath.filename * exn
| `CannotCopyDir of FilePath.filename
| `CannotCopyFilesToFile of FilePath.filename list * FilePath.filename
| `CannotCreateDir of FilePath.filename * exn
| `CannotListSrcDir of FilePath.filename * exn
| `CannotOpenDstFile of FilePath.filename * exn
| `CannotOpenSrcFile of FilePath.filename * exn
| `CannotRemoveDstFile of FilePath.filename * exn
| `DstDirNotDir of FilePath.filename
| `ErrorRead of FilePath.filename * exn
| `ErrorWrite of FilePath.filename * exn
| `Exc of exn
| `NoSourceFile of FilePath.filename
| `PartialWrite of FilePath.filename * int * int
| `SameFile of FilePath.filename * FilePath.filename
| `UnhandledType of FilePath.filename * kind

]

Possible cp errors.

val cp : 
  ?follow:action_link ->
  ?force:interactive ->
  ?recurse:bool ->
  ?preserve:bool ->
  ?error:cp_error error_handler ->
  FilePath.filename list ->
  FilePath.filename ->
  unit

Copy the hierarchy of files/directory to another destination. See POSIX documentation.

mv

exception MvError of string

type mv_error = [

| `Exc of exn
| `MvCp of FilePath.filename * FilePath.filename * string * cp_error
| `MvRm of FilePath.filename * string * rm_error
| `NoSourceFile

]

Possible mv errors.

val mv : 
  ?error:mv_error error_handler ->
  ?force:interactive ->
  FilePath.filename ->
  FilePath.filename ->
  unit

Move files/directories to another destination. See POSIX documentation.

touch

type touch_time_t = FileUtil.touch_time_t =

| Touch_now
(*
Use Unix.gettimeofday
*)
| Touch_file_time of FilePath.filename
(*
Get mtime of file
*)
| Touch_timestamp of float
(*
Use GMT timestamp
*)

Time for file

val touch : 
  ?atime:bool ->
  ?mtime:bool ->
  ?create:bool ->
  ?time:touch_time_t ->
  FilePath.filename ->
  unit

Modify the timestamp of the given filename. See POSIX documentation. If atime and mtime are not specified, they are both considered true. If only atime or mtime is sepcified, the other is false.

parameter atime
modify access time.

parameter mtime
modify modification time.

parameter create
if file doesn't exist, create it, default true

parameter time
what time to set, default Touch_now

ls

val filter : test_file -> FilePath.filename list -> FilePath.filename list

Apply a filtering pattern to a filename.

val ls : FilePath.filename -> FilePath.filename list

List the content of a directory. See POSIX documentation.

Misc operations

val pwd : unit -> FilePath.filename

Return the current dir. See POSIX documentation.

val readlink : FilePath.filename -> FilePath.filename

Resolve to the real filename removing symlink. Non POSIX command.

val which : 
  ?path:FilePath.filename list ->
  FilePath.filename ->
  FilePath.filename

Try to find the executable in the PATH. Use environement variable PATH if none is provided. Non POSIX command.

val cmp : 
  ?skip1:int ->
  FilePath.filename ->
  ?skip2:int ->
  FilePath.filename ->
  int option

cmp skip1 fln1 skip2 fln2 Compare files fln1 and fln2 starting at pos skip1 skip2 and returning the first octect where a difference occurs. Returns Some -1 if one of the file is not readable or if it is not a file. See POSIX documentation.

val du : FilePath.filename list -> size * (FilePath.filename * size) list

du fln_lst Return the amount of space of all the file which are subdir of fln_lst. Also return details for each file scanned. See POSIX documentation.

val find : 
  ?follow:action_link ->
  ?match_compile:(FilePath.filename -> FilePath.filename -> bool) ->
  test_file ->
  FilePath.filename ->
  ('a -> FilePath.filename -> 'a) ->
  'a ->
  'a

find ~follow:fol tst fln exec accu Descend the directory tree starting from the given filename and using the test provided. You cannot match current_dir and parent_dir. For every file found, the action exec is done, using the accu to start. For a simple file listing, you can use find True "." (fun x y -> y :: x) [] See POSIX documentation.

For future release:

val pathchk: filename -> boolean * string, check whether file names are valid or portable
val setfacl: filename -> permission -> unit, set file access control lists (UNIX + extended attribute)
val getfacl: filename -> permission, get file access control lists

ACL related function will be handled through a plugin system to handle at runtime which attribute can be read/write (i.e. Win32 ACL, NFS acl, Linux ACL -- or none).

include module type of struct include FilePath end

type filename = string

Filename type.

type extension = string

Extension type.

Exceptions and types

exception BaseFilenameRelative of filename

Cannot pass a base filename which is relative.

exception UnrecognizedOS of string

We do not have recognized any OS, please contact upstream.

exception EmptyFilename

The filename use was empty.

exception NoExtension of filename

The last component of the filename does not support extension (Root, ParentDir...)

exception InvalidFilename of filename

The filename used is invalid.

Ordering

val is_subdir : filename -> filename -> bool

is_subdir child parent Is child really a sub directory of parent

val is_updir : filename -> filename -> bool

is_updir parent child Is parent really a parent directory of child

val compare : filename -> filename -> int

compare fl1 fl2 Give an order between the two filename. The classification is done by sub directory relation, fl1 < fl2 iff fl1 is a subdirectory of fl2, and lexicographical order of each part of the reduce filename when fl1 and fl2 has no hierarchical relation

Standard operations

val current_dir : filename

Current dir.

val parent_dir : filename

Upper dir.

val make_filename : string list -> filename

Make a filename from a set of strings.

val basename : filename -> filename

Extract only the file name of a filename. Returns an empty string for directory-only paths like "dir/".

val dirname : filename -> filename

Extract the directory name of a filename. Returns an empty string for file-only paths like "file".

val concat : filename -> filename -> filename

Append a filename to a filename.

val reduce : ?no_symlink:bool -> filename -> filename

Return the shortest filename which is equal to the filename given. It remove the "." in Unix filename, for example. If no_symlink flag is set, consider that the path doesn't contain symlink and in this case ".." for Unix filename are also reduced.

val make_absolute : filename -> filename -> filename

Create an absolute filename from a filename relative and an absolute base filename.

val make_relative : filename -> filename -> filename

Create a filename which is relative to the base filename.

val reparent : filename -> filename -> filename -> filename

reparent fln_src fln_dst fln Return the same filename as fln but the root is no more fln_src but fln_dst. It replaces the fln_src prefix by fln_dst.

val identity : filename -> filename

Identity for testing the stability of implode/explode.

val is_valid : filename -> bool

Test if the filename is a valid one.

val is_relative : filename -> bool

Check if the filename is relative to a dir or not.

val is_current : filename -> bool

Check if the filename is the current directory.

val is_parent : filename -> bool

Check if the filename is the parent directory.

Extension

Extension is define as the suffix of a filename, just after the last ".".

val chop_extension : filename -> filename

Remove extension and the trailing ".".

val get_extension : filename -> extension

Extracts the extension. Raises Not_found if there is no extension.

val check_extension : filename -> extension -> bool

Check the extension.

val add_extension : filename -> extension -> filename

Add an extension with a "." before. Using this function with an empty extension string creates a filename with a trailing dot.

val replace_extension : filename -> extension -> filename

Replace extension.

PATH-like operation

PATH-like refers the environment variable PATH. This variable holds a list of filename. The functions string_of_path and path_of_string allow to convert this kind of list by using the good separator between filename.

val string_of_path : filename list -> string

Create a PATH-like string.

val path_of_string : string -> filename list

Extract filenames from a PATH-like string.

Filename specifications

Definition of operations for path manipulation.

module type PATH_SPECIFICATION = FilePath.PATH_SPECIFICATION

Generic operations.

module type PATH_STRING_SPECIFICATION = FilePath.PATH_STRING_SPECIFICATION

Generic operations, with type filename and extension as strings.

Operations on filenames for other OS. The DefaultPath always match the current OS.

module DefaultPath = FilePath.DefaultPath

Default operating system.

module UnixPath = FilePath.UnixPath

Unix operating system.

module Win32Path = FilePath.Win32Path

Win32 operating system.

module CygwinPath = FilePath.CygwinPath

Cygwin operating system.

val ensure_trailing : Base.String.t -> Base.String.t

val join : Base.String.t list -> Base.String.t

package spin