-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A file-packing application.
--   
--   Returns progressively better subsets of the specified files, selected
--   to fit into a limited space, without wasting more than the specific
--   ratio.
@package squeeze
@version 1.0.4.13


-- | <ul>
--   <li><i><tt>AUTHOR</tt></i> Dr. Alistair Ward</li>
--   <li><i><tt>DESCRIPTION</tt></i> Defines file-related type-synonyms,
--   and associated operations.</li>
--   </ul>
module Squeeze.Data.File

-- | A type suitable for containing an arbitrary set of file-paths.
type FilePathList = [FilePath]

-- | A type-synonym specifically to hold file-sizes (in bytes).
type FileSize = Integer

-- | A type suitable for containing a file-path, qualified by the
--   corresponding <a>FileSize</a>.
type FileSizeAndPath = (FileSize, FilePath)

-- | <ul>
--   <li>Returns the cumulative sequence of sizes, as each file is
--   prepended to the specified list.</li>
--   <li>CAVEAT: the list-length is one greater than that supplied, since
--   the last element represents the size with zero files.</li>
--   </ul>
accumulateSize :: [FileSizeAndPath] -> [FileSize]

-- | Sum the <a>FileSize</a>s in the specified list.
aggregateSize :: [FileSizeAndPath] -> FileSize

-- | <ul>
--   <li>Finds any file-paths which have been specified more than
--   once.</li>
--   <li>This includes files which have been implicitly specified via a
--   directory.</li>
--   </ul>
findDuplicates :: FilePathList -> IO FilePathList

-- | Finds file-sizes.
findSizes :: FilePathList -> IO [FileSizeAndPath]

-- | Sorts a list of <a>FileSizeAndPath</a> by increasing size; ie.
--   smallest first.
orderByIncreasingSize :: [FileSizeAndPath] -> [FileSizeAndPath]

-- | Sorts a list of <a>FileSizeAndPath</a> by decreasing size; ie.
--   smallest first.
orderByDecreasingSize :: [FileSizeAndPath] -> [FileSizeAndPath]

-- | Acquire statistics related to a list of files.
getFileSizeStatistics :: (Fractional mean, Floating standardDeviation) => [FileSizeAndPath] -> (Int, FileSize, mean, standardDeviation)

-- | <ul>
--   <li>Partitions the specified list of file-sizes &amp; paths, into
--   those whose size is suitable according to the specified predicate
--   &amp; those which are unsuitable.</li>
--   <li>Logs the results.</li>
--   </ul>
selectSuitableFileSizes :: (FileSize -> Bool) -> [FileSizeAndPath] -> Writer [String] [FileSizeAndPath]

-- | Accessor.
getSize :: FileSizeAndPath -> FileSize

-- | Accessor.
getPath :: FileSizeAndPath -> FilePath

-- | True if the specified file has the required size according to the
--   specified predicate.
hasSizeBy :: (FileSize -> Bool) -> FileSizeAndPath -> Bool


-- | <ul>
--   <li><i><tt>AUTHOR</tt></i> Dr. Alistair Ward</li>
--   <li><i><tt>DESCRIPTION</tt></i> A data-type which references a set of
--   files by their paths, and qualifies them with their aggregate
--   size.</li>
--   </ul>
module Squeeze.Data.FileCombination

-- | Declare a list of files qualified by its aggregate size.
data FileCombination

-- | A constant empty instance.
nullFileCombination :: FileCombination

-- | Compares two <i>file-combination</i>s by their aggregate file-size.
comparingAggregateFileSize :: FileCombination -> FileCombination -> Ordering

-- | <ul>
--   <li>Prepend a <a>FileSizeAndPath</a> to an existing
--   <a>FileCombination</a>.</li>
--   <li>CAVEAT: performance hot-spot, so it by-passes the checks made by
--   <a>mkFileCombination</a>.</li>
--   </ul>
prepend :: FileSizeAndPath -> FileCombination -> FileCombination

-- | Progressively raises the selection-criterion as each match is found,
--   to produce monotonically increasing file-combinations.
risingFilter :: FileSize -> [FileCombination] -> [FileCombination]

-- | Merges two lists of monotonically increasing lists of
--   file-combinations, into a single monotonically increasing list, by
--   dropping values which have a smaller aggregate size than results
--   already found.
risingMergeByAggregateFileSize :: [FileCombination] -> [FileCombination] -> [FileCombination]

-- | Smart constructor.
mkFileCombination :: FileSize -> FilePathList -> FileCombination

-- | Construct a <a>FileCombination</a> from a single
--   <a>FileSizeAndPath</a>.
singleton :: FileSizeAndPath -> FileCombination

-- | Predicate used to determine whether a specific file-combination
--   matches a size-related requirement.
hasSizeBy :: (FileSize -> Bool) -> FileCombination -> Bool
instance GHC.Classes.Eq Squeeze.Data.FileCombination.FileCombination
instance GHC.Show.Show Squeeze.Data.FileCombination.FileCombination
instance ToolShed.SelfValidate.SelfValidator Squeeze.Data.FileCombination.FileCombination


-- | <ul>
--   <li><i><tt>AUTHOR</tt></i> Dr. Alistair Ward</li>
--   <li><i><tt>DESCRIPTION</tt></i></li>
--   </ul>
--   
--   <ul>
--   <li>Defines options for program-operation.</li>
--   <li>Defines an appropriate default value, which is expected to be
--   over-ridden on the command-line.</li>
--   <li>Self-validates.</li>
--   </ul>
module Squeeze.Data.CommandOptions

-- | Declares a record to contain command-line options.
data CommandOptions ratio

-- | The bounds on the aggregate size of the set of files.
solutionSizeBounds :: RealFrac f => CommandOptions f -> Interval FileSize

-- | Derives the minimum number of bytes, from other options.
deriveMinimumBytes :: RealFrac ratio => CommandOptions ratio -> FileSize

-- | Reduce the requirements by the specified file-size.
subtractFile :: RealFrac ratio => FileSize -> CommandOptions ratio -> CommandOptions ratio

-- | Smart constructor.
mkCommandOptions :: (Ord ratio, Real ratio) => Bool -> FileSize -> Maybe Int -> ratio -> Verbosity -> CommandOptions ratio
instance GHC.Show.Show ratio => GHC.Show.Show (Squeeze.Data.CommandOptions.CommandOptions ratio)
instance GHC.Classes.Eq ratio => GHC.Classes.Eq (Squeeze.Data.CommandOptions.CommandOptions ratio)
instance GHC.Real.Fractional f => Data.Default.Class.Default (Squeeze.Data.CommandOptions.CommandOptions f)
instance (GHC.Classes.Ord ratio, GHC.Real.Real ratio) => ToolShed.SelfValidate.SelfValidator (Squeeze.Data.CommandOptions.CommandOptions ratio)


-- | <ul>
--   <li><i><tt>AUTHOR</tt></i> Dr. Alistair Ward</li>
--   <li><i><tt>DESCRIPTION</tt></i></li>
--   </ul>
--   
--   Provides the capability to write two unevaluated lists to separate
--   concurrent channels, read them both &amp; merge the results into a
--   single list, evaluating in parallel, lazily on demand.
module Squeeze.Control.Concurrent.DivideAndConquer

-- | Writes the two unevaluated lists to separate concurrent channels,
--   lazily reads them both (resulting in parallel evaluation) &amp; merges
--   them into a single results-list.
divideAndConquer :: ([a] -> [a] -> [a]) -> [a] -> [a] -> IO [a]


-- | <ul>
--   <li><i><tt>AUTHOR</tt></i> Dr. Alistair Ward</li>
--   <li><i><tt>DESCRIPTION</tt></i></li>
--   </ul>
--   
--   <ul>
--   <li>Returns combinations of the specified files, which fit into the
--   available space, without wasting more than the specified ratio.</li>
--   <li>Any directory-names are treated as atomic units, rather than
--   individual files.</li>
--   <li>Because of the exponential growth of possible combinations, an
--   <i>exact</i> match for the available space is frequently found with a
--   surprisingly small set of files.</li>
--   </ul>
module Squeeze.Squeeze

-- | <ul>
--   <li>Checks that the total aggregate <a>FileSize</a>, meets or exceeds
--   <tt>minimumBytes</tt>.</li>
--   <li>Drops excessively large files, assuming that the file-list has
--   been sorted by size, largest first.</li>
--   <li>Generates up to <tt>2^n</tt> combinations of the <tt>n</tt>
--   specified files; the algorithm is similar to <a>subsequences</a>,
--   except that unproductive lines are immediately terminated. This is the
--   performance bottle-neck, and though there may be simpler and faster
--   algorithms, the key attribute is that it operates in constant
--   space.</li>
--   <li>CAVEAT: assumes files have been sorted by decreasing size.</li>
--   <li>The algorithm is stable, in that it maintains the specified
--   file-order within each combination; though the order in which the
--   combinations are concatenated is rather arbitrary.</li>
--   </ul>
findCombinations :: Interval FileSize -> [FileSizeAndPath] -> [FileCombination]

-- | Orders the files by decreasing size, calls <a>findCombinations</a>,
--   calls <a>risingFilter</a> to select progressively better solutions.
findBestFit :: Interval FileSize -> [FileSizeAndPath] -> [FileCombination]

-- | <ul>
--   <li>Recursively bisects the task, distributing the sub-tasks to
--   <a>findBestFit</a>, to utilise the available CPU-cores.</li>
--   <li>The task is bisected by removing the smallest file, then solving
--   the remaining problem for two independent cases; that the selected
--   file is excluded or the selected file is included, in the final
--   solution. Selecting the smallest file rather than the largest, seems
--   to balance the load of the sub-tasks more evenly. CAVEAT: no account
--   has been taken of the possibility that the smallest file has size
--   zero, which makes the sub-tasks identical.</li>
--   <li>Recombines the part solutions to finds the single monotonically
--   increasing list of file-combinations matching the original
--   criteria.</li>
--   <li>CAVEAT: whilst the ultimate solution is similar, regardless of the
--   specified number of CPU-cores available, the path leading to it
--   typically differs.</li>
--   </ul>
distributeAndFindBestFit :: RealFrac ratio => CommandOptions ratio -> [FileSizeAndPath] -> IO [FileCombination]

-- | <ul>
--   <li>Neither <a>distributeAndFindBestFit</a> nor <a>findBestFit</a>
--   distinguish between empty &amp; non-empty files, but empty files cause
--   significant inefficiency in the former (where the same calculation is
--   performed multiple times) &amp; could be treated much more efficiently
--   in the latter (since they're potentially a member of any other
--   solution).</li>
--   <li>This function side-lines empty files, delegates the remaining
--   problem to <a>distributeAndFindBestFit</a> (&amp; consequently
--   <a>findBestFit</a>), then prepends combinations of empty files to the
--   resulting combinations of non-empty files.</li>
--   </ul>
partitionEmptyFilesAndDistributeAndFindBestFit :: RealFrac ratio => CommandOptions ratio -> [FileSizeAndPath] -> IO [FileCombination]