diff --git a/Sources/MathParser/Documentation.docc/GettinStarted.md b/Sources/MathParser/Documentation.docc/GettinStarted.md index 69ce940..ec473b0 100644 --- a/Sources/MathParser/Documentation.docc/GettinStarted.md +++ b/Sources/MathParser/Documentation.docc/GettinStarted.md @@ -1,4 +1,4 @@ -# Overview +# Getting Started Basic math expression parser built with Point•Free's swift-parsing package (v0.12.0). diff --git a/Sources/MathParser/MathParser.swift b/Sources/MathParser/MathParser.swift index 19f9d52..2642173 100644 --- a/Sources/MathParser/MathParser.swift +++ b/Sources/MathParser/MathParser.swift @@ -37,7 +37,7 @@ final public class MathParser { public typealias BinaryFunctionMap = (String) -> BinaryFunction? /// Dictionary of binary function names and their implementations. public typealias BinaryFunctionDict = [String: BinaryFunction] - /// Return value for the `parseResult` method. + /// Return value for the ``MathParser/parseResult(_:)`` method. public typealias Result = Swift.Result /** Default symbols to use for parsing. @@ -152,8 +152,8 @@ final public class MathParser { Parse an expression into a token that can be evaluated at a later time. - parameter text: the expression to parse - - returns: optional Evaluator to use to obtain results from the parsed expression. This is nil if - the given expression is not valid. + - returns: optional ``Evaluator`` to use to obtain results from the parsed expression. This is nil if + the given expression to parse is not valid. */ public func parse(_ text: String) -> Evaluator? { guard let token = try? expression.parse(text) else { return nil } @@ -161,7 +161,10 @@ final public class MathParser { } /** - Parse an expression into a token that can be evaluated at a later time. Returns a `Result` enum with two cases: + Parse an expression into a token that can be evaluated at a later time, and returns a `Result` value that conveys + information about the parsing result. + + The `Result` enum has two cases: - `.success` -- holds an ``Evaluator`` instance for evaluations of the parsed expression - `.failure` -- holds a ``MathParserError`` instance that describes the parse failure @@ -180,7 +183,7 @@ final public class MathParser { // MARK: - implementation details - /// When true, two parsed operands in a row implies multiplication + // When true, two parsed operands in a row implies multiplication private let enableImpliedMultiplication: Bool // Any of these will terminate an identifier (as well as whitespace). NOTE: this must be kept up-to-date with any @@ -198,7 +201,7 @@ final public class MathParser { "," ] - /** + /* Parser for a numeric constant. NOTE: we disallow signed numbers here due to ambiguities that are introduced if implied multiplication mode is enabled. We allow for negative values through the negation operation which demands that the "-" appear just before the number without any spaces between them. @@ -224,19 +227,19 @@ final public class MathParser { End() } - // NOTE: the chain of expression parsers from here to exponentiation causes a loop so we need to be Lazy here. + // NOTE: the chain of expression parsers from here to exponentiation causes a loop so we need to be "lazy" here. private lazy var subexpression: some TokenParser = Lazy { self.additionAndSubtraction } - lazy var additionAndSubtraction = InfixOperation( + private lazy var additionAndSubtraction = InfixOperation( name: "+|-", associativity: .left, operator: additionOrSubtractionOperator, operand: multiplicationAndDivision ) - lazy var multiplicationAndDivision = InfixOperation( + private lazy var multiplicationAndDivision = InfixOperation( name: "*|/", associativity: .left, operator: multiplicationOrDivisionOperator, @@ -244,7 +247,7 @@ final public class MathParser { implied: enableImpliedMultiplication ? self.multiplicationReducer : nil ) - lazy var exponentiation = InfixOperation( + private lazy var exponentiation = InfixOperation( name: "Pow", associativity: .right, operator: exponentiationOperator, diff --git a/docs/data/documentation/mathparser.json b/docs/data/documentation/mathparser.json index 132d86a..5dc7b94 100644 --- a/docs/data/documentation/mathparser.json +++ b/docs/data/documentation/mathparser.json @@ -169,7 +169,7 @@ "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/GettinStarted", "kind" : "article", "role" : "article", - "title" : "Overview", + "title" : "Getting Started", "type" : "topic", "url" : "\/documentation\/mathparser\/gettinstarted" }, diff --git a/docs/data/documentation/mathparser/gettinstarted.json b/docs/data/documentation/mathparser/gettinstarted.json index 613fee0..d828a59 100644 --- a/docs/data/documentation/mathparser/gettinstarted.json +++ b/docs/data/documentation/mathparser/gettinstarted.json @@ -25,7 +25,7 @@ ], "role" : "article", "roleHeading" : "Article", - "title" : "Overview" + "title" : "Getting Started" }, "primaryContentSections" : [ { @@ -924,7 +924,7 @@ "doc://MathParser/documentation/MathParser/MathParser/parseResult(_:)": { "abstract" : [ { - "text" : "Parse an expression into a token that can be evaluated at a later time. Returns a ", + "text" : "Parse an expression into a token that can be evaluated at a later time, and returns a ", "type" : "text" }, { @@ -932,7 +932,15 @@ "type" : "codeVoice" }, { - "text" : " enum with two cases:", + "text" : " value that conveys", + "type" : "text" + }, + { + "text" : " ", + "type" : "text" + }, + { + "text" : "information about the parsing result.", "type" : "text" } ], diff --git a/docs/data/documentation/mathparser/mathparser.json b/docs/data/documentation/mathparser/mathparser.json index a9fcb6b..51d8e97 100644 --- a/docs/data/documentation/mathparser/mathparser.json +++ b/docs/data/documentation/mathparser/mathparser.json @@ -518,8 +518,9 @@ "type" : "text" }, { - "code" : "parseResult", - "type" : "codeVoice" + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/MathParser\/parseResult(_:)", + "isActive" : true, + "type" : "reference" }, { "text" : " method.", @@ -1193,7 +1194,7 @@ "doc://MathParser/documentation/MathParser/MathParser/parseResult(_:)": { "abstract" : [ { - "text" : "Parse an expression into a token that can be evaluated at a later time. Returns a ", + "text" : "Parse an expression into a token that can be evaluated at a later time, and returns a ", "type" : "text" }, { @@ -1201,7 +1202,15 @@ "type" : "codeVoice" }, { - "text" : " enum with two cases:", + "text" : " value that conveys", + "type" : "text" + }, + { + "text" : " ", + "type" : "text" + }, + { + "text" : "information about the parsing result.", "type" : "text" } ], diff --git a/docs/data/documentation/mathparser/mathparser/parse(_:).json b/docs/data/documentation/mathparser/mathparser/parse(_:).json index 65d1fbf..502ad37 100644 --- a/docs/data/documentation/mathparser/mathparser/parse(_:).json +++ b/docs/data/documentation/mathparser/mathparser/parse(_:).json @@ -163,7 +163,16 @@ { "inlineContent" : [ { - "text" : "optional Evaluator to use to obtain results from the parsed expression. This is nil if", + "text" : "optional ", + "type" : "text" + }, + { + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/Evaluator", + "isActive" : true, + "type" : "reference" + }, + { + "text" : " to use to obtain results from the parsed expression. This is nil if", "type" : "text" }, { @@ -171,7 +180,7 @@ "type" : "text" }, { - "text" : "the given expression is not valid.", + "text" : "the given expression to parse is not valid.", "type" : "text" } ], diff --git a/docs/data/documentation/mathparser/mathparser/parseresult(_:).json b/docs/data/documentation/mathparser/mathparser/parseresult(_:).json index e16fd24..ee57aff 100644 --- a/docs/data/documentation/mathparser/mathparser/parseresult(_:).json +++ b/docs/data/documentation/mathparser/mathparser/parseresult(_:).json @@ -1,7 +1,7 @@ { "abstract" : [ { - "text" : "Parse an expression into a token that can be evaluated at a later time. Returns a ", + "text" : "Parse an expression into a token that can be evaluated at a later time, and returns a ", "type" : "text" }, { @@ -9,7 +9,15 @@ "type" : "codeVoice" }, { - "text" : " enum with two cases:", + "text" : " value that conveys", + "type" : "text" + }, + { + "text" : " ", + "type" : "text" + }, + { + "text" : "information about the parsing result.", "type" : "text" } ], @@ -207,6 +215,23 @@ "text" : "Discussion", "type" : "heading" }, + { + "inlineContent" : [ + { + "text" : "The ", + "type" : "text" + }, + { + "code" : "Result", + "type" : "codeVoice" + }, + { + "text" : " enum has two cases:", + "type" : "text" + } + ], + "type" : "paragraph" + }, { "items" : [ { @@ -408,8 +433,9 @@ "type" : "text" }, { - "code" : "parseResult", - "type" : "codeVoice" + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/MathParser\/parseResult(_:)", + "isActive" : true, + "type" : "reference" }, { "text" : " method.", @@ -446,7 +472,7 @@ "doc://MathParser/documentation/MathParser/MathParser/parseResult(_:)": { "abstract" : [ { - "text" : "Parse an expression into a token that can be evaluated at a later time. Returns a ", + "text" : "Parse an expression into a token that can be evaluated at a later time, and returns a ", "type" : "text" }, { @@ -454,7 +480,15 @@ "type" : "codeVoice" }, { - "text" : " enum with two cases:", + "text" : " value that conveys", + "type" : "text" + }, + { + "text" : " ", + "type" : "text" + }, + { + "text" : "information about the parsing result.", "type" : "text" } ], diff --git a/docs/data/documentation/mathparser/mathparser/result.json b/docs/data/documentation/mathparser/mathparser/result.json index 99f3ba6..39ed12e 100644 --- a/docs/data/documentation/mathparser/mathparser/result.json +++ b/docs/data/documentation/mathparser/mathparser/result.json @@ -5,8 +5,9 @@ "type" : "text" }, { - "code" : "parseResult", - "type" : "codeVoice" + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/MathParser\/parseResult(_:)", + "isActive" : true, + "type" : "reference" }, { "text" : " method.", @@ -260,8 +261,9 @@ "type" : "text" }, { - "code" : "parseResult", - "type" : "codeVoice" + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/MathParser\/parseResult(_:)", + "isActive" : true, + "type" : "reference" }, { "text" : " method.", @@ -295,6 +297,77 @@ "type" : "topic", "url" : "\/documentation\/mathparser\/mathparser\/result" }, +"doc://MathParser/documentation/MathParser/MathParser/parseResult(_:)": { + "abstract" : [ + { + "text" : "Parse an expression into a token that can be evaluated at a later time, and returns a ", + "type" : "text" + }, + { + "code" : "Result", + "type" : "codeVoice" + }, + { + "text" : " value that conveys", + "type" : "text" + }, + { + "text" : " ", + "type" : "text" + }, + { + "text" : "information about the parsing result.", + "type" : "text" + } + ], + "fragments" : [ + { + "kind" : "keyword", + "text" : "func" + }, + { + "kind" : "text", + "text" : " " + }, + { + "kind" : "identifier", + "text" : "parseResult" + }, + { + "kind" : "text", + "text" : "(" + }, + { + "kind" : "typeIdentifier", + "preciseIdentifier" : "s:SS", + "text" : "String" + }, + { + "kind" : "text", + "text" : ") -> " + }, + { + "kind" : "typeIdentifier", + "preciseIdentifier" : "s:10MathParserAAC", + "text" : "MathParser" + }, + { + "kind" : "text", + "text" : "." + }, + { + "kind" : "typeIdentifier", + "preciseIdentifier" : "s:10MathParserAAC6Resulta", + "text" : "Result" + } + ], + "identifier" : "doc:\/\/MathParser\/documentation\/MathParser\/MathParser\/parseResult(_:)", + "kind" : "symbol", + "role" : "symbol", + "title" : "parseResult(_:)", + "type" : "topic", + "url" : "\/documentation\/mathparser\/mathparser\/parseresult(_:)" +}, "doc://MathParser/documentation/MathParser/MathParserError": { "abstract" : [ { diff --git a/docs/index/index.json b/docs/index/index.json index e94deb2..c09c300 100644 --- a/docs/index/index.json +++ b/docs/index/index.json @@ -14,7 +14,7 @@ }, { "path" : "\/documentation\/mathparser\/gettinstarted", - "title" : "Overview", + "title" : "Getting Started", "type" : "article" }, {