Add an a sample CLI app that uses null safety (#55)

null_safety/calculate_lix/.gitignore

@@ -0,0 +1,12 @@
+# Files and directories used by the Dart SDK
+.dart_tool/
+.packages
+build/
+doc/api/
+
+# Android Studio configuration
+.idea/
+!.idea/runConfigurations/Run_main_with_test_data.xml
+
+# VSCode configuration
+.vscode/settings.json

null_safety/calculate_lix/.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Dart",
+            "program": "bin/main.dart",
+            "request": "launch",
+            "type": "dart",
+            "vmAdditionalArgs": [
+                "--enable-experiment=non-nullable",
+            ],
+            "args": [
+                "text/lorem-ipsum.txt"
+            ]
+        }
+    ]
+}

null_safety/calculate_lix/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version

null_safety/calculate_lix/LICENSE

@@ -0,0 +1,26 @@
+Copyright 2020, the Dart project authors. All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

null_safety/calculate_lix/README.md

@@ -0,0 +1,77 @@
+# Null safety example: A CLI-app for calculating lix
+
+This is a small code example of an app that calculates the 'lix' readability
+index for a text file. The implementation uses the new Dart null safety feature,
+and is meant to demonstrate how this feature works in a practical example,
+as well as serve as a demonstration of how to configure and run code with null
+safety at it's current tech preview stage.
+
+## Running the example code
+
+The code works only with the first tech preview of null safety, Dart SDK version
+`2.9.0-13.0.dev`. You will need to download a copy of this Dart SDK even if you
+have a Flutter or Dart SDK installed already, and you'll want to use this
+preview SDK only for experimenting with null safety. Specifically, do not use it
+for any kind of production coding.
+
+### Dart preview SDK installation
+
+  1. Download the tech preview 1 build is version **`2.9.0-13.0.dev`** from the
+     dev-channel in the SDK archive:
+     https://dart.dev/tools/sdk/archive#dev-channel
+
+  1. Unzip the SDK to a folder, e.g. `/Users/michael/dev/preview/dart-sdk` or
+     `C:\Users\michael\dev\preview\dart-sdk\`
+
+### Running from the terminal/command-prompt
+
+Because null safety is still in tech preview, we need to pass a so-called
+'experiment flag' when invoking and Dart command in the terminal, which looks
+like this: `--enable-experiment=non-nullable`.
+
+To run the main app, type these commands in the terminal/command-prompt:
+
+  - Windows:
+    - `cd <folder with samples repo>\null_safety\calculate_lix\`
+    - `C:\Users\michael\dev\preview\dart-sdk\bin\dart --enable-experiment=non-nullable bin\main.dart text\lorem-ipsum.txt`
+  - macOS/Linux:
+    - `cd <folder with samples repo>/null_safety/calculate_lix/`
+    - `/Users/michael/dev/preview/dart-sdk/bin/dart --enable-experiment=non-nullable bin/main.dart text/lorem-ipsum.txt`
+
+### Running from VSCode
+
+This example contains a launch configuration for VSCode that runs
+`bin/main.dart` passing both the experimental flag, so to run the sample in
+VSCode:
+
+  1. Edit your VSCode configuration to point to one additional Dart SDK, the
+     preview SDK we just downloaded. See [details
+     here](https://dartcode.org/docs/quickly-switching-between-sdk-versions/)
+     for what values to put in Code > Preferences > Settings.
+
+  1. Invoke File > Open, and select the `calculate_lix` folder
+
+  1. Tell VSCode to use the preview Dart SDK: Open `bin/main.dart` and then
+     locate the 'Dart: <version number>' selector in the status bar at the
+     bottom, and select `Dart: 2.9.0-13.0.dev`.
+
+  1. Press F5 and the project should run and print a message in the Debug
+     Console.
+
+
+### Running from Android Studio
+
+  1. Start Android Studio
+
+  1. Select Open Project, and select the `calculate_lix` folder
+
+  1. Open the file `bin/main.dart` in the code editor
+
+  1. Select 'Open Dart Settings' in the top banner
+
+  1. Select both 'Enable Dart support' checkmarks at the top and bottom of the dialog.
+
+  1. Under Dart SDK specify the path to the Dart preview SDK (2.9.0-13.0.dev). Click OK.
+
+  1. Select Run > Run and the project should run and print a message in the Run
+     pane.

null_safety/calculate_lix/analysis_options.yaml

@@ -0,0 +1,3 @@
+analyzer:
+  enable-experiment:
+    - non-nullable

null_safety/calculate_lix/bin/main.dart

@@ -0,0 +1,39 @@
+// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:calculate_lix/lix.dart';
+
+void main(List<String> arguments) {
+  // Parse the arguments; we expect a single argument containing the file name.
+  if (arguments.length != 1) {
+    printUsage();
+    exit(64);
+  } else {
+    // Get the file name.
+    //
+    // TIP: We're using null safe versions of the core libraries, and the type
+    // of `arguments` is `List` which means that arguments cannot contain null
+    // elements. As a result, the Dart analyzer knows that `fileName` isn't
+    // null.
+    final fileName = arguments[0];
+    print("Calculating Lix of '$fileName'");
+
+    // Calculate lix.
+    try {
+      final l = Lix.fromString(File(fileName).readAsStringSync());
+      print("Lix is: ${l.readability}, ${l.describe()} to read ("
+          "words: ${l.words}, long words: ${l.longWords}, "
+          "periods: ${l.periods}).");
+    } catch (ArgumentError) {
+      print(
+          'Invalid input, could not calculate lix!\nThe input text must contain at least one full sentence.');
+    }
+  }
+}
+
+void printUsage() {
+  print('Usage: calculate_lix <text file>');
+}