Fix docs

Author: Sominemo

CHANGELOG.md

@@ -1,96 +1,101 @@
+# 1.5.1
+
+-   Increased upper SDK constraint to declare support for Dart 3
+-   Documentation fixes
+
 # 1.5.0
 
 ## Breaking changes
 
-- Now the `'` symbol is allowed for variable and function names so you can have variables like `y'`.
+-   Now the `'` symbol is allowed for variable and function names so you can have variables like `y'`.
 
 ## Equations
 
-- Implemented `>=` and `<=`.
+-   Implemented `>=` and `<=`.
 
 # 1.4.0
 
 ## Custom Functions
 
-- Define custom functions and redefine built-in functions when parsing
-  an expression. See docs and example.
-- Use `MathNodeExpression.getPotentialFunctionNames()` to detect potentially
-  used functions in a string.
-- Use period in the middle of custom variable and function names.
-- Under-hood, functions now support multiple comma separated arguments, so
-  you can supply multiple arguments to your custom function.
-- Detect custom functions im math tree using
-  `MathExpression.getUsedFreeformFunctions()`.
+-   Define custom functions and redefine built-in functions when parsing
+    an expression. See docs and example.
+-   Use `MathNodeExpression.getPotentialFunctionNames()` to detect potentially
+    used functions in a string.
+-   Use period in the middle of custom variable and function names.
+-   Under-hood, functions now support multiple comma separated arguments, so
+    you can supply multiple arguments to your custom function.
+-   Detect custom functions im math tree using
+    `MathExpression.getUsedFreeformFunctions()`.
 
 ## Breaking Changes
 
-- `MissingFunctionArgumentListException` renamed to
-  `OutOfRangeFunctionArgumentListException`
-- `MathNodeExpression.fromString()` may throw other errors besides
-  `MathException`
-- `MathNodeExpression.getPotentialVariableNames()` is replaced by
-  `MathNodeExpression.getPotentialDefinable()`
-- Instead of `log[base](arg)`, you should pass `log(base, arg)` syntax now
-- Period is an allowed character in the middle of a variable name now
+-   `MissingFunctionArgumentListException` renamed to
+    `OutOfRangeFunctionArgumentListException`
+-   `MathNodeExpression.fromString()` may throw other errors besides
+    `MathException`
+-   `MathNodeExpression.getPotentialVariableNames()` is replaced by
+    `MathNodeExpression.getPotentialDefinable()`
+-   Instead of `log[base](arg)`, you should pass `log(base, arg)` syntax now
+-   Period is an allowed character in the middle of a variable name now
 
 ## Misc.
 
-- `UnexpectedClosingBracketException` and `BracketsNotClosedException` can
-  now tell where the problem probably happened.
-- New MathParseException's `InvalidFunctionNameException`,
-  `DuplicateDeclarationException`, `InvalidFunctionArgumentsDeclaration`.
+-   `UnexpectedClosingBracketException` and `BracketsNotClosedException` can
+    now tell where the problem probably happened.
+-   New MathParseException's `InvalidFunctionNameException`,
+    `DuplicateDeclarationException`, `InvalidFunctionArgumentsDeclaration`.
 
 # 1.3.1
 
-- Variable validation fix
+-   Variable validation fix
 
 # 1.3.0
 
 ## Math Tree
 
-- Important change: `MathNode` is now a class of `MathExpression` interface.
-  Compared to MathNode, MathExpression may return null in `calc()` method.
-- New: `getUsedVariables()` method for `MathExpression` and `MathNode`.
-  This method goes down the math tree to find any uses of `MathVariable`
-  and returns names of all variables.
-- New: `MathExpression` object family - `MathComparison`:
-  - `MathComparisonEquation` (=)
-  - `MathComparisonGreater` (>)
-  - `MathComparisonLess` (<)
+-   Important change: `MathNode` is now a class of `MathExpression` interface.
+    Compared to MathNode, MathExpression may return null in `calc()` method.
+-   New: `getUsedVariables()` method for `MathExpression` and `MathNode`.
+    This method goes down the math tree to find any uses of `MathVariable`
+    and returns names of all variables.
+-   New: `MathExpression` object family - `MathComparison`:
+    -   `MathComparisonEquation` (=)
+    -   `MathComparisonGreater` (>)
+    -   `MathComparisonLess` (<)
 
 ## Parsing
 
-- New: `MathNodeExpression.fromStringExtended()` method allows you to
-  interpret equations and comparisons. Compared to `fromString`,
-  it returns `MathExpression` instead of `MathNode`, since comparisons
-  can't guarantee result.
-- New: `MathNodeExpression.getPotentialVariableNames()` analyzes given
-  math expression string for possible use of variables. Refer to
-  documentation for rough edges before using it.
-- New: `MathNodeExpression.builtInVariables` gives a list of built-in
-  predefined variable names.
-- New: `MathNodeExpression.isVariableNameValid()` lets you check if
-  the parser can work with a given name.
+-   New: `MathNodeExpression.fromStringExtended()` method allows you to
+    interpret equations and comparisons. Compared to `fromString`,
+    it returns `MathExpression` instead of `MathNode`, since comparisons
+    can't guarantee result.
+-   New: `MathNodeExpression.getPotentialVariableNames()` analyzes given
+    math expression string for possible use of variables. Refer to
+    documentation for rough edges before using it.
+-   New: `MathNodeExpression.builtInVariables` gives a list of built-in
+    predefined variable names.
+-   New: `MathNodeExpression.isVariableNameValid()` lets you check if
+    the parser can work with a given name.
 
 ## Misc.
 
-- Changed input parameters type for `CantProcessExpressionException`.
-- Small documentation fixes.
+-   Changed input parameters type for `CantProcessExpressionException`.
+-   Small documentation fixes.
 
 # 1.2.0
 
-- Fix README.
-- Moved integrating features to a separate package library
-  `math_parser_integrate`.
+-   Fix README.
+-   Moved integrating features to a separate package library
+    `math_parser_integrate`.
 
 # 1.1.0
 
-- Custom variables support.
-- `MathFunctionX`deprecated.
-- `MathVariable` introduced.
-- You need to pass an instance of `MathVariableValues` instead of a num
-  to the `calc()` function now.
+-   Custom variables support.
+-   `MathFunctionX`deprecated.
+-   `MathVariable` introduced.
+-   You need to pass an instance of `MathVariableValues` instead of a num
+    to the `calc()` function now.
 
 # 1.0.0
 
-- Initial version.
+-   Initial version.

README.md

@@ -8,38 +8,98 @@ parts of equations and other forms of simple math
 expressions in your projects. This package supports custom
 variables too.
 
+## TL;DR How to parse and calculate an expression
+
+### Predefined list of variables
+
+```dart
+import 'package:math_parser/math_parser.dart';
+
+void main() {
+  final expression = MathNodeExpression.fromString(
+  '(2x)^(e^3 + 4) + y',
+  variableNames: {'x', 'y'},
+  ).calc(
+    MathVariableValues({'x': 20, 'y': 10}),
+  );
+}
+```
+
+### Autodetect variables
+
+Implicit multiplication (writing `2x` instead of `2*x`) is not supported for auto-detecting variables.
+Trying to use auto-detection on expressions with implicit multiplication may cause a `CantProcessExpressionException` during parsing or unexpected parsing results.
+
+```dart
+import 'dart:io';
+import 'package:math_parser/math_parser.dart';
+
+void main() {
+  final stringExpression = '(2*x)^(e^3 + 4) + y';
+  print('Expression: $stringExpression');
+
+  final definable = MathNodeExpression.getPotentialDefinable(
+    stringExpression,
+    hideBuiltIns: true,
+  );
+
+  final expression = MathNodeExpression.fromString(
+    stringExpression,
+    variableNames: definable.variables,
+    isImplicitMultiplication: false,
+  );
+
+  // Ask user to define variables
+  final variableValues = <String, double>{};
+  for (final variable in definable.variables) {
+    print('Enter value for $variable:');
+    final double value = double.parse(
+      stdin.readLineSync() as String,
+    );
+    variableValues[variable] = value;
+  }
+
+  final result = expression.calc(
+    MathVariableValues(variableValues),
+  );
+
+  print('Result: $result');
+}
+```
+
 ## Features: In Short
-For more details about these features, refer to documentation, 
-this readme or example file. All public API elements are 
+
+For more details about these features, refer to documentation,
+this readme or example file. All public API elements are
 documented.
 
-- Parse mathematical expressions using 
-  `MathNodeExpression.fromString` or equations using 
-  `MathNodeExpression.fromStringExtended`.
-- Define custom variables and functions by passing 
-  `variableNames` and `customFunctions` parameters. To define
-  a custom function, you'll have to implement the 
-  `MathDefinitionFunctionFreeformImplemented` interface for 
-  each such function.
-- Automatically detect possible variable and function names used in 
-  an expression, but this works reliably only with implicit 
-  multiplication off.
+-   Parse mathematical expressions using
+    `MathNodeExpression.fromString` or equations using
+    `MathNodeExpression.fromStringExtended`.
+-   Define custom variables and functions by passing
+    `variableNames` and `customFunctions` parameters. To define
+    a custom function, you'll have to implement the
+    `MathDefinitionFunctionFreeformImplemented` interface for
+    each such function.
+-   Automatically detect possible variable and function names used in
+    an expression, but this works reliably only with implicit
+    multiplication off.
 
-## Math Tree
+## Advanced use: Math Tree
 
 The library provides a family of `MathExpression` and
 `MathNode` classes, most of them have subnodes that are being
 calculated recursively.
 
 There are such types of MathNode:
 
-- `MathFunction` (and `MathFunctionWithTwoArguments` subclass)
-- `MathValue`
-- `MathOperator`
+-   `MathFunction` (and `MathFunctionWithTwoArguments` subclass)
+-   `MathValue`
+-   `MathOperator`
 
 Types of `MathExpression`:
 
-- `MathComparison`
+-   `MathComparison`
 
 All the child classes names begin with the family they belong to.
 
@@ -90,11 +150,11 @@ you don't need to redeclare the function in `MathExpression.calc`.
    functions have the same requirements, except they can override built-in
    functions.
 3. Functions (case-sensitive):
-   - Custom functions
-   - sin, cos, tan (tg), cot (ctg)
-   - sqrt (√) (interpreted as power of 1/2), complex numbers not supported
-   - ln (base=E), lg (base=2), log\[base\]\(x\)
-   - asin (arcsin), acos (arccos), atan (arctg), acot (arcctg)
+    - Custom functions
+    - sin, cos, tan (tg), cot (ctg)
+    - sqrt (√) (interpreted as power of 1/2), complex numbers not supported
+    - ln (base=E), lg (base=2), log\[base\]\(x\)
+    - asin (arcsin), acos (arccos), atan (arctg), acot (arcctg)
 4. Unary minus (-) at the beginning of a block
 5. Power (x^y)
 6. Implicit multiplication (two MathNodes put near without operator between)

analysis_options.yaml

@@ -1,15 +1,16 @@
 include: package:lints/recommended.yaml
 analyzer:
-  strong-mode:
-    implicit-casts: false
-    implicit-dynamic: false
   language:
     strict-raw-types: true
+    strict-inference: true
+    strict-casts: true
 linter:
   rules:
     always_declare_return_types: true
     prefer_single_quotes: true
     unawaited_futures: true
     package_api_docs: true
+    public_member_api_docs: true
+    type_annotate_public_apis: true
     prefer_final_in_for_each: true
     prefer_final_locals: true

lib/math_parser.dart

@@ -2,20 +2,66 @@
 ///
 /// A simple library done for tasks like function evaluation
 ///
-/// Example for parsing a string and calculating it with x = 20.
 /// Look at [MathNodeExpression]'s `fromString` method for more info about
 /// how parsing works.
 ///
-/// ```dart
-/// import 'package:math_parser/math_parser.dart';
+///## Parsing TL;DR
+///### Predefined list of variables
 ///
-/// void main() {
-///   final expression = MathNodeExpression.fromString(
-///     '(2x)^(e^3 + 4)',
-///   );
-///   print(expression.calc(20));
-/// }
-/// ```
+///```dart
+///import 'package:math_parser/math_parser.dart';
+///
+///void main() {
+///  final expression = MathNodeExpression.fromString(
+///  '(2x)^(e^3 + 4) + y',
+///  variableNames: {'x', 'y'},
+///  ).calc(
+///    MathVariableValues({'x': 20, 'y': 10}),
+///  );
+///}
+///```
+///
+///### Autodetect variables
+///
+///Implicit multiplication (writing `2x` instead of `2*x`) is not supported for auto-detecting variables.
+///Trying to use auto-detection on expressions with implicit multiplication may cause a `CantProcessExpressionException` during parsing or unexpected parsing results.
+///
+///```dart
+///import 'dart:io';
+///import 'package:math_parser/math_parser.dart';
+///
+///void main() {
+///  final stringExpression = '(2*x)^(e^3 + 4) + y';
+///  print('Expression: $stringExpression');
+///
+///  final definable = MathNodeExpression.getPotentialDefinable(
+///    stringExpression,
+///    hideBuiltIns: true,
+///  );
+///
+///  final expression = MathNodeExpression.fromString(
+///    stringExpression,
+///    variableNames: definable.variables,
+///    isImplicitMultiplication: false,
+///  );
+///
+///  // Ask user to define variables
+///  final variableValues = <String, double>{};
+///  for (final variable in definable.variables) {
+///    print('Enter value for $variable:');
+///    final double value = double.parse(
+///      stdin.readLineSync() as String,
+///    );
+///    variableValues[variable] = value;
+///  }
+///
+///  final result = expression.calc(
+///    MathVariableValues(variableValues),
+///  );
+///
+///  print('Result: $result');
+///}
+///```
 library math_parser;
 
 export 'src/math_node.dart';