wet-pancake/WetPancake/ProductServices.fs

namespace WetPancake

/// This module contains all the public functions in the Wet Pancake NuGet package.
/// It enables you to generate random text.
module  Pancake =

    open SystemServices
    open DataAccess
    open DataProcessing
    open DataStructuring
    open DataServices
    open System
    open System.IO

    /// <summary>
    /// Checks to see if the string matches the desired sentence count and removes any over that limit.
    /// This function is ascynchronous.
    /// </summary>
    /// <param name="noOfSentences">
    /// The number of sentences the cleaned string should have.
    /// This should be smaller than the number of sentences the original text has.
    /// </param>
    /// <param name="text">
    /// The string to clean.
    /// </param>
    /// <returns>
    /// A string of text which has been trimmed to the specified sentence count.
    /// </returns>
    /// <exception cref="System.InvalidOperationException">
    /// Thrown when the number of sentences requested is bigger than the number in the text passed in.
    /// </exception>
    /// <remarks>
    /// This function's aim is to trim or remove excess sentences.
    /// If the string has less sentences than the number requested, it will not change.
    /// </remarks>
    let CleanResultAsync noOfSentences text =
        async {
            try
                let cleanText =
                    text
                    |> RemoveArtefactSentences noOfSentences
                return cleanText
            with
            | :? InvalidOperationException -> return text
        }

    /// <summary>
    /// Checks the text within the specified file to see if it contains a vaild end token.
    /// They are '.', '!' and '?'.
    /// </summary>
    /// <param name="filePath">
    /// The path of the .txt file being tested.
    /// </param>
    /// <remarks>
    /// This function does not check to see if the filepath is valid.
    /// Be sure to check the path is valid before calling this function.
    /// </remarks>
    let TextInFileIsValidAsync filePath =
        async {
            return DataAccess.LoadFile filePath |> TextContainsValidEndToken
        }

    /// <summary>
    /// An asynchronous function which generates random text.
    /// </summary>
    /// <returns>
    /// A string of randomly generated text.
    /// </returns>
    /// <remarks>
    /// This function will produce a maximum of 10 sentences with each function call.
    /// </remarks>
    let RequestRandomTextAsync () =
        async  {
            let data =
                LoadFile (SelectRandomSampleFile())
                |> ApplyStandardSetup
                |> SortIntoGroups (PickRandomNumber 2 10)
                |> GenerateMap
            return GenerateMarkovText (PickRandomNumber 2 10) data
        }

    /// <summary>
    /// An asynchronous function which generates random text. 
    /// It uses the built-in template (.txt) files as a reference and the parameters specified by the caller.
    /// </summary>
    /// <param name="gibberishLevel">
    /// Specifies how coherent the generated text is.
    /// Min. value = 2. Max. value = 20.
    /// The lower the value the more gibberish it will produce.
    /// </param>
    /// <param name="sentences">
    /// Specifies the number of sentences to generate.
    /// </param>
    /// <returns>
    /// A string of randomly generated text.
    /// </returns>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "gibberishLevel" is not between 2 and 20.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "sentences" count is less than 1.
    /// </exception>
    /// <remarks>
    /// The higher the “gibberishLevel” and the “sentences” count is the longer it will take to complete the task.
    /// Try to make the most of the asynchronous nature of the function as possible.
    ///</remarks>
    let RequestTextAsync (gibberishLevel: int) (sentences: int) =
        async {
            try
                GibberishLevelIsValid gibberishLevel |> ignore
                SentencesIsValid sentences |> ignore
                let data =
                    LoadFile (SelectRandomSampleFile())
                    |> ApplyStandardSetup
                    |> SortIntoGroups gibberishLevel
                    |> GenerateMap
                return GenerateMarkovText sentences data
            with
            | :? ArgumentException as ex -> return ex.Message
        }

    /// <summary>
    /// An asynchronous function which generates text. 
    /// It generates the text by using the (.txt) file passed in by the caller (as the reference)
    /// It, also, uses the parameters specified by the caller.
    /// </summary>
    /// <param name="gibberishLevel">
    /// Specifies how coherent the generated text is.
    /// Min. value = 2. Max. value = 20.
    /// The lower the value the more gibberish it will produce.
    /// </param>
    /// <param name="sentences">
    /// Specifies the number of sentences to generate.
    /// </param>
    /// <param name="filePath">
    /// The path of the (.txt) file the function will use as the reference text. 
    /// </param>
    /// <returns>
    /// A string of randomly generated text.
    /// </returns>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "gibberishLevel" is not between 2 and 20.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "sentences" count is less than 1.
    /// </exception>
    /// <exception cref="System.FileNotFoundException">
    /// Thrown when the (.txt) file cannot be found.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the specified file is not a plain-text (.txt) file.
    /// </exception>
    /// <remarks>
    /// The higher the “gibberishLevel” and the “sentences” count is the longer it will take to complete the task.
    /// This, also, applies to the (.txt) file passed into the function.
    /// The bigger it is, the longer it will take to read.
    /// Try to make the most of the asynchronous nature of the function as possible.
    /// Also, the function does not know what is in the (.txt) file until it reads it.
    /// Defensive coding should be applied here.
    /// </remarks>
    let RequestTextFromFileAsync (gibberishLevel: int) (sentences: int) (filePath: string) =
        async {
            try
                GibberishLevelIsValid gibberishLevel |> ignore
                SentencesIsValid sentences |> ignore
                FilePathIsValid filePath |> ignore
                let! textIsValid = TextInFileIsValidAsync filePath
                if textIsValid = true then ignore ()
                else failwith @"The .txt file does not contain an end token ('.', '!' or '?')."
                let data =
                    LoadFile filePath
                    |> ApplyStandardSetup
                    |> SortIntoGroups gibberishLevel
                    |> GenerateMap
                return GenerateMarkovText sentences data
            with
            | :? ArgumentException as ex -> return ex.Message
            | :? FileNotFoundException as ex -> return ex.Message
            | :? SystemException as ex -> return ex.Message
        }

    /// <summary>
    /// Finds every available template (.txt) file in Wet Pancake and forms a list of their file paths.
    /// </summary>
    /// <returns>
    /// A list of every template (.txt) file path.
    /// </returns>
    /// <remarks>
    /// You can use the information provided by this function alongside the "RequestTextFromFileAsync” function.
    /// This allows you to generate text using one of the built-in template (.txt) files.
    /// </remarks>
    let RequestAllTemplateFiles () =
        ListSampleFiles
        |> Array.toList

    /// <summary>
    /// An asynchronous function which generates random text.
    /// It uses the built-in template (.txt) files as a reference and the parameters specified by the user.
    /// It, also, goes through a "cleaning" process which removes any excess sentences.
    /// </summary>
    /// <param name="gibberishLevel">
    /// Specifies how coherent the generated text is.
    /// Min. value = 2. Max. value = 20.
    /// The lower the value the more gibberish it will produce.</param>
    /// <param name="sentences">
    /// Specifies the number of sentences to generate.
    /// </param>
    /// <returns>
    /// A string of randomly generated text.
    /// </returns>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "gibberishLevel" is not between 2 and 20.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "sentences" count is less than 1.
    /// </exception>
    /// <remarks>
    /// This function produces more accurate results than the equivalent RequestTextAsync.
    /// Although, it does take loner to complete.
    /// If you can tolerate the odd extra sentences and prefer speed, use RequestextAsync.
    /// If not, use this.
    /// </remarks> 
    let RequestCleanTextAsync (gibberishLevel: int) (sentences: int) =
        async {
            let! text = RequestTextAsync gibberishLevel sentences
            let! cleanText = CleanResultAsync sentences text
            return cleanText
        }

    /// <summary>
    /// An asynchronous function which generates text. 
    /// It generates the text by using the (.txt) file passed in by the caller (as the reference)
    /// It, also, uses the parameters specified by the caller.
    /// On top of that, it goes through a "cleaning" process which removes any excess sentences.
    /// </summary>
    /// <param name="gibberishLevel">
    /// Specifies how coherent the generated text is.
    /// Min. value = 2. Max. value = 20.
    /// The lower the value the more gibberish it will produce.
    /// </param>
    /// <param name="sentences">
    /// Specifies the number of sentences to generate.
    /// </param>
    /// <param name="filePath">
    /// The path of the (.txt) file the function will use as the reference text. 
    /// </param>
    /// <returns>
    /// A string of randomly generated text.
    /// </returns>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "gibberishLevel" is not between 2 and 20.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the "sentences" count is less than 1.
    /// </exception>
    /// <exception cref="System.FileNotFoundException">
    /// Thrown when the (.txt) file cannot be found.
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// Thrown when the specified file is not a plain-text (.txt) file.
    /// </exception>
    /// <remarks>
    /// The higher the “gibberishLevel” and the “sentences” count is the longer it will take to complete the task.
    /// This, also, applies to the (.txt) file passed into the function.
    /// The bigger it is, the longer it will take to read.
    /// Try to make the most of the asynchronous nature of the function as possible.
    /// Also, the function does not know what is in the (.txt) file until it reads it.
    /// Defensive coding should be applied here.
    /// This function produces more accurate results than it RequestTextFromFileAsync equivalent.
    /// Although, it does take loner to complete.
    /// If you can tolerate the odd extra sentences and prefer speed, use RequestextAsync.
    /// If not, use this.
    /// </remarks>
    let RequestCleanTextFromFileAsync (gibberishLevel: int) (sentences: int) (filePath: string) =
        async {
            let! text = RequestTextFromFileAsync gibberishLevel sentences filePath
            let! cleanText = CleanResultAsync sentences text
            return cleanText
        }