updated readme

README.md

@@ -6,11 +6,11 @@ This module allows creating simple interfaces to forms/payloads for use in HTTP
 
 A form is defined by its fields. 
 
-A field is defined by an **alias** (for internal use) and the field's **name**, which is the parameter name in the payload sent during a `POST` request, and which typically corresponds to the `name` attribute of a `<select>` or `<input>` HTML tag.
+A field is defined by its _name_, which is the parameter name in the payload sent during a `POST` request, and which typically corresponds to the `name` attribute of a `<select>` or `<input>` HTML tag.
 
-Optionally, a field can have a **default** value, value **options** (as `<select>` tags do), and may be declared **required** (i.e. non-optional).
+Optionally, a field can have an _alias_ (for internal use), a _default_ value, value _options_ (as `<select>` tags do), and may be declared _required_.
 
-A form definition in YAML format will consist of the field aliases as top-level keys, and the corresponding fields' definitions as key-value-pairs below them.
+A form definition in YAML format will consist of the field names as top-level keys, and either nothing/`null` or the corresponding fields' definitions as key-value-pairs below them.
 
 ## Example
 
@@ -18,19 +18,16 @@ A form definition in YAML format will consist of the field aliases as top-level
 ```yaml
 # definition.yaml
 
-field1:
-  name: payload_param_1
-field2:
-  name: payload_param_2
-  default: foo
+way_too_long_field_name:
+  alias: short_name
+foo: 
 choice_field:
-  name: payload_param_3
   options:
     value1: text for option 1
     value2: text for option 2
   default: value1
 mandatory_field:
-  name: payload_param_0
+  alias: special
   required: true
 ```
 
@@ -38,10 +35,11 @@ mandatory_field:
 ```
 >>> from yamlhttpforms import load_form
 >>> form_interface = load_form('definition.yaml')
->>> form_interface.get_payload(field1='abc', field2='bar', mandatory_field='420')
-{'payload_param_1': 'abc', 'payload_param_2': 'bar', 'payload_param_3': 'value1', 'payload_param_0': '420'}
->>> form_interface.get_payload(field1='abc', choice_field='baz', mandatory_field='420')
+>>> form_interface.get_payload(short_name='abc', foo='bar', special='420')
+{'way_too_long_field_name': 'abc', 'foo': 'bar', 'choice_field': 'value1', 'mandatory_field': '420'}
+
+>>> form_interface.get_payload(short_name='abc', choice_field='baz', special='420')
 Traceback (most recent call last):
   ...
-ValueError: "baz" is not a valid option for <SelectField: name="payload_param_3", default="value1", options={'value1': 'text for option 1', 'value2': 'text for option 2'}>
+ValueError: "baz" is not a valid option for <SelectField: name="choice_field", default="value1", options={'value1': 'text for option 1', 'value2': 'text for option 2'}>
 ```