Update README to reflect current feature set

novoda · Nov 14, 2016 · 6e2ee2f · 6e2ee2f
1 parent 8481c27
commit 6e2ee2f
Showing 1 changed file with 88 additions and 80 deletions.
diff --git a/README.md b/README.md
@@ -32,91 +32,48 @@ buildscript {
   }
 }
 ```
-Then apply the plugin in your buildscript **after the android plugin** via:  
+Then apply the plugin in your build script via:
 ```gradle
 apply plugin: 'com.novoda.build-properties'
 ```
 
 ## Simple usage
-Add a `buildProperties` configuration to your android buildscript listing
-all the properties files you intend to reference in your `android` configuration:
+Add a `buildProperties` configuration to your build script listing
+all the properties files you intend to reference later on:
 ```gradle
 buildProperties {
     secrets {
         file project.file('secrets.properties')
     }
 }
-
-android {
-    ...
-}
 ```
 where `secrets.properties` is a properties file that can now be referenced
-in the buildscript as `buildProperties.secrets`.   
-
-## Features
-
-#### 1. Store a property value into your `BuildConfig`
-In any product flavor configuration (or `defaultConfig`) you can use
-`buildConfigProperty` as follows:
+in the build script as `buildProperties.secrets`. Entries in such file can be
+accessed via the `getAt` operator:
 ```gradle
-    defaultConfig {
-        ...
-        buildConfigProperty 'API_KEY', buildProperties.secrets['apiKey']
-        ...
-    }
+Entry entry = buildProperties.secrets['aProperty']
 ```
 
-#### 2. Store a property value as generated string resource
-In any product flavor configuration (or `defaultConfig`) you can use
-`resValueProperty` as follows:
+The value of an `Entry`` can be retrieved via one of its typed accessors:
 
-```gradle
-    defaultConfig {
-        ...
-        resValueProperty 'api_key', buildProperties.secrets['apiKey']
-        ...
-    }
-```
+- `boolean enabled = buildProperties.secrets['x'].boolean`
+- `int count = buildProperties.secrets['x'].int`
+- `double rate = buildProperties.secrets['x'].double`
+- `String label = buildProperties.secrets['x'].string`
 
-#### 3. Load signing configuration from properties
-Instead of inline your passwords and other details in your build script
-you can fill the signing configuration using a properties file.
-```gradle
-signingConfigs {
-  release {
-    signingConfigProperties buildProperties.releaseSigning
-  }
-}
+Is important to note that values are lazily accessed too (via the internal closure provided in `Entry`).
+Trying to access the value of a specific property could generate an exception
+if the key is missing in the provided properties file, eg:
 ```
-The plugin will automatically retrieve all the needed fields from the
-properties file. Note: the path of the keystore file is considered relative
-to the path of the specified properties file.
+FAILURE: Build failed with an exception.
 
-## Bonus
+* What went wrong:
+A problem occurred configuring project ':app'.
+> No value defined for property 'notThere' in 'secrets' properties (/Users/toto/novoda/spikes/BuildPropertiesPlugin/sample/properties/secrets.properties)
 
-#### Typed `buildConfigField` / `resValue`
-The plugin enhances the `buildConfigField` and `resValue` facilities to
-enforce types. To generate a string field in your `BuildConfig` you used to write:
-```gradle
-buildConfigField 'String', 'LOL', '\"sometimes the picture take\"'
-```
-but now you can instead write:
-```gradle
-buildConfigString 'LOL', 'sometimes the picture take'
 ```
-The full list of new typed facilities is as follows:
 
-| | Example |
-|----|----|
-|`buildConfigBoolean` | `buildConfigBoolean 'TEST_BOOLEAN', false`|
-|`buildConfigInt` | `buildConfigInt 'TEST_INT', 42`|
-|`buildConfigLong` | `buildConfigLong 'TEST_LONG', System.currentTimeMillis()`|
-|`buildConfigDouble` | `buildConfigDouble 'TEST_DOUBLE', Math.PI`|
-|`buildConfigString` | `buildConfigString 'TEST_STRING', 'whateva'`|
-|`resValueInt`| `resValueInt 'debug_test_int', 100`|
-|`resValueBoolean` | `resValueBoolean 'debug_test_bool', true`|
-|`resValueString` | `resValueString 'debug_test_string', 'dunno bro...'`|
+## Features
 
 #### Fallback support
 If a property cannot be found an exception is thrown. It's possible to provide a fallback
@@ -128,7 +85,7 @@ value for a given `Entry` via the `or()` operator, defined as:
 |a `Closure` | `buildProperties.secrets['notThere'].or({ Math.random() })` |
 |a value | `buildProperties.secrets['notThere'].or('fallback')` |
 
-If the whole fallback chain evaluation fails a `CompositeException` is thrown listing all
+If the whole fallback chain evaluation fails then a `CompositeException` is thrown listing all
 the causes in the chain, eg:
 
 ```
@@ -161,30 +118,81 @@ fallback values.
 
 #### More on loading properties
 If the specified file is not found an exception is thrown at build time as soon as one of its properties is evaluated.
-You can specify a custom error message to provide the user with more information.
+You can specify a custom error message to provide the user with more information, eg:
+```gradle
+buildProperties {
+    secrets {
+        file rootProject.file('secrets.properties'), '''
+           This file should contain the following properties:
+           - fabricApiKey: API key for Fabric
+           - googleMapsApiKey: API key for Google Maps
+        '''
+    }
+}
+```
+
 
-Given a `BuildProperties` instance one of its entries can be retrieved using the `getAt` operator:
+## Android-specific features
 
+When applying the `gradle-build-properties-plugin` to an Android project you get access to and
+ additional set of poerful features.
+
+#### 1. Store a property value into your `BuildConfig`
+In any product flavor configuration (or `defaultConfig`) you can use
+`buildConfigProperty` as follows:
 ```gradle
-Entry entry = buildProperties.secrets['aProperty']
+    defaultConfig {
+        ...
+        buildConfigProperty 'API_KEY', buildProperties.secrets['apiKey']
+        ...
+    }
 ```
 
-The value of an entry can be retrieved via one of the following typed accessors:
-
-- `entry.getBoolean()`, or `entry.boolean`
-- `entry.getInt()`, or `entry.int`
-- `entry.getDouble()`, or `entry.double`
-- `entry.getString()`, or `entry.string`
+#### 2. Store a property value as generated string resource
+In any product flavor configuration (or `defaultConfig`) you can use
+`resValueProperty` as follows:
 
-If you want to access the raw value (`Object`) you can also use `entry.getValue()`/`entry.value`.
-Is important to note that values are lazily accessed too (via the internal closure provided in `Entry`).
-Trying to access the value of a specific property could generate an exception
-if the key is missing in the provided properties file, eg:
+```gradle
+    defaultConfig {
+        ...
+        resValueProperty 'api_key', buildProperties.secrets['apiKey']
+        ...
+    }
 ```
-FAILURE: Build failed with an exception.
 
-* What went wrong:
-A problem occurred configuring project ':app'.
-> No value defined for property 'notThere' in 'secrets' properties (/Users/toto/novoda/spikes/BuildPropertiesPlugin/sample/properties/secrets.properties)
+#### 3. Load signing configuration from properties
+Instead of inline your passwords and other details in your build script
+you can fill the signing configuration using a properties file.
+```gradle
+signingConfigs {
+  release {
+    signingConfigProperties buildProperties.releaseSigning
+  }
+}
+```
+The plugin will automatically retrieve all the needed fields from the
+properties file. Note: the path of the keystore file is considered relative
+to the path of the specified properties file.
 
+#### 4. Typed `buildConfigField` / `resValue`
+The plugin enhances the `buildConfigField` and `resValue` facilities to
+enforce types. To generate a string field in your `BuildConfig` you used to write:
+```gradle
+buildConfigField 'String', 'LOL', '\"sometimes the picture take\"'
 ```
+but now you can instead write:
+```gradle
+buildConfigString 'LOL', 'sometimes the picture take'
+```
+The full list of new typed facilities is as follows:
+
+| | Example |
+|----|----|
+|`buildConfigBoolean` | `buildConfigBoolean 'TEST_BOOLEAN', false`|
+|`buildConfigInt` | `buildConfigInt 'TEST_INT', 42`|
+|`buildConfigLong` | `buildConfigLong 'TEST_LONG', System.currentTimeMillis()`|
+|`buildConfigDouble` | `buildConfigDouble 'TEST_DOUBLE', Math.PI`|
+|`buildConfigString` | `buildConfigString 'TEST_STRING', 'whateva'`|
+|`resValueInt`| `resValueInt 'debug_test_int', 100`|
+|`resValueBoolean` | `resValueBoolean 'debug_test_bool', true`|
+|`resValueString` | `resValueString 'debug_test_string', 'dunno bro...'`|