ua-parser · selwin · Nov 9, 2013 · Nov 9, 2013 · Nov 10, 2013 · Nov 10, 2013
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+.DS_Store
+node_modules/
 *.pyc
 *.egg-info/
 .eggs/

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,18 @@
+Contributing Changes to regexes.yaml
+------------------------------------
+
+Contributing to the project, especially `regexes.yaml`, is both welcomed and encouraged. To do so just do the following:
+
+1. Fork the project
+2. Create a branch for your changes
+3. Modify `regexes.yaml` as appropriate
+4. Add relevant tests to the following files and follow their format:
+	* `tests/test_device.yaml`
+	* `tests/test_os.yaml`
+	* `tests/test_ua.yaml`
+5. Push your branch to GitHub and submit a pull request
+6. Monitor the pull request to make sure the Travis build succeeds. If it fails simply make the necessary changes to your branch and push it. Travis will re-test the changes.
+
+That's it. If you don't feel comfortable forking the project or modifying the YAML you can also [submit an issue](https://github.com/ua-parser/uap-core/issues) that includes the appropriate user agent string and the expected results of parsing.
+
+Thanks!
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,16 @@
+Apache License, Version 2.0
+===========================
+
+Copyright 2009 Google Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/README.md b/README.md
@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 #uap-python
 A python implementation of the UA Parser (https://github.com/ua-parser, formerly https://github.com/tobie/ua-parser)
 
@@ -87,3 +88,39 @@ make Makefile
 
 Copyright 2008 Google Inc. See ua_parser/LICENSE for more information 
 
+=======
+uap-core [![Build Status](https://secure.travis-ci.org/ua-parser/uap-core.png?branch=master)](https://travis-ci.org/ua-parser/uap-core)
+========
+
+This repository contains the core of [BrowserScope][2]'s original [user agent string parser][3]: data collected over the years by [Steve Souders][4] and numerous other contributors, extracted into a separate [YAML file][5] so as to be reusable _as is_ by implementations in any programming language.
+
+This repo itself does _not_ contain a parser: only the necessary data to build one. There exists a ref implementation, along with multiple, production-ready implementations in various programming languages.
+
+Maintainers
+-----------
+
+* [Lindsey Simon](https://github.com/elsigh) ([@elsigh](https://twitter.com/elsigh))
+* [Tobie Langel](https://github.com/tobie) ([@tobie](https://twitter.com/tobie))
+
+Communication channels
+-----------------------
+
+* \#ua-parser on freenode <irc://chat.freenode.net#ua-parser>
+* [mailing list](https://groups.google.com/forum/#!forum/ua-parser)
+
+Contributing Changes to regexes.yaml
+------------------------------------
+
+Please read the [contributors' guide](CONTRIBUTING.md)
+
+License
+-------
+
+The data contained in `regexes.yaml` is Copyright 2009 Google Inc. and available under the [Apache License, Version 2.0][6].
+
+[2]: http://www.browserscope.org
+[3]: http://code.google.com/p/ua-parser/
+[4]: http://stevesouders.com/
+[5]: https://raw.github.com/ua-parser/uap-core/master/regexes.yaml
+[6]: http://www.apache.org/licenses/LICENSE-2.0
+>>>>>>> 0adc0716a0976ea0472a43d32e7c7a5f584b4e30
diff --git a/docs/specification.md b/docs/specification.md
@@ -0,0 +1,204 @@
+# ua-parser Specification
+
+Version 0.2 Draft
+
+This document describes the specification on how a parser must implement the `regexes.yaml` file for correctly parsing user-agent strings on basis of that file.
+
+This specification intends to help maintainers and contributors to correctly use the provided information within the `regexes.yaml` file for obtaining information from the different user-agent strings. Furthermore this specification tries to be the basis for discussions on evolving the projects and the needed parsing algorithms.
+
+This document will not provide any information on how to implement the ua-parser project on your server and how to retreive the user-agent string for further processing.
+
+# `regexes.yaml`
+
+Any information which can be obtained from a user-agent string may contain information on:
+
+* User-Agent aka “the browser”
+* OS (Operating System) the User-Agent currently uses (or runs on)
+* Device information by means of the physical device the User-Agent is using
+
+This information is provided within the `regexes.yaml` file. Each kind of information requires a different parser which extracts the related type. These are:
+
+* `user_agent_parser`
+* `os_parsers`
+* `device_parsers`
+
+Each parser contains a list of regular-expressions which are named `regex`. For each `regex` replacements specific to the parser can be named to attribute or change information. A replacement may require a match from the regular-expression which is extracted by an expression enclosed in normal brackets `"()"`. Each match can be addressed with `$1` to `$9` and used in a parser specific replacement.
+
+**TODO**: Provide some insights into the used chars. E.g. escape `"."` as `"\."` and `"("` as `"\("`. `"/"` does not need to be escaped.
+
+## `user_agent_parsers`
+
+The `user_agent_parsers` returns information of the `family` type of the User-Agent.
+If available the version infomation specifying the `family` may be extracted as well if available.
+Here major, minor and patch version information can be addressed or overwritten.
+
+| match in regex | default replacement | placeholder in replacement | note    |
+| ---- | ------------------- | ---- | --------------------------------------- |
+| 1    | family_replacement  | $1   | specifies the User-Agents family        |
+| 2    | v1_replacement      | $2   | major version number/info of the family |
+| 3    | v2_replacement      | $3   | minor version number/info of the family |
+| 4    | v3_replacement      | $4   | patch version number/info of the family |
+
+In case that no replacement is specified, the association is given by order of the match. If in the `regex` no first match (within normal brackets) is given, the `family_replacement` shall be specified!
+To overwrite the respective value the replacement value needs to be named for a `regex`-item.
+
+**Parser Implementation:**
+
+The list of regular-expressions `regex` shall be evaluated for a given user-agent string beginning with the first `regex`-item in the list to the last item. The first matching `regex` stops processing the list. Regex-matching shall be case sensitive.
+
+In case that no replacement for a match is specified for a `regex`-item, the first match defines the `family`, the second `major`, the third `minor`and the forth `patch` information.
+If a `*_replacement` string is specified it shall overwrite or replace the match.
+
+As placeholder for inserting matched characters use within
+* `family_replacement`: `$1`
+* `v1_replacement`: `$2`
+* `v2_replacement`: `$3`
+* `v3_replacement`: `$4`
+
+If no matching `regex` is found the value for `family` shall be “Other”. The version information `major`, `minor` and `patch` shall not be defined.
+
+**Example:**
+
+For the User-Agent: `Mozilla/5.0 (Windows; Windows NT 5.1; rv:2.0b3pre) Gecko/20100727 Minefield/4.0.1pre`
+the matching `regex`:
+
+```
+  - regex: '(Namoroka|Shiretoko|Minefield)/(\d+)\.(\d+)\.(\d+(?:pre)?)'
+    family_replacement: 'Firefox ($1)'
+```
+
+resolves to:
+
+```
+  family: Firefox (Minefield)
+  major : 4
+  minor : 0
+  patch : 1pre
+```
+
+## `os_parsers`
+
+The `os_parsers` return information of the `os` type of the Operating System (OS) the User-Agent runs.
+If available the version information specifying the `os` may be extracted as well if available.
+Here major, minor and patch version information can be addressed or overwritten.
+
+| match in regex | default replacement | placeholder in replacement | note   |
+| ---- | ----------------- | ---- | ---------------------------------------- |
+| 1    | os_replacement    | $1   | specifies the OS                         |
+| 2    | os_v1_replacement | $2   | major version number/info of OS          |
+| 3    | os_v2_replacement | $3   | minor version number/info of the OS      |
+| 4    | os_v3_replacement | $4   | patch version number/info of the OS      |
+| 5    | os_v4_replacement | $5   | patchMinor version number/info of the OS |
+
+In case that no replacement is specified, the association is given by order of the match. If in the `regex` no first match (within normal brackets) is given, the `os_replacement` shall be specified!
+To overwrite the respective value the replacement value needs to be named for a `regex`-item.
+
+**Parser Implementation:**
+
+The list of regular-expressions `regex` shall be evaluated for a given user-agent string beginning with the first `regex`-item in the list to the last item. The first matching `regex` stops processing the list. Regex-matching shall be case sensitive.
+
+In case that no replacement for a match is specified for a `regex`-item, the first match defines the `os` family, the second `major`, the third `minor`, the forth `patch` and the fifth `patchMinor` version information.
+If a `*_replacement` string is specified it shall overwrite or replace the match.
+
+As placeholder for inserting matched characters use within
+* `os_replacement`: `$1`
+* `os_v1_replacement`: `$2`
+* `os_v2_replacement`: `$3`
+* `os_v3_replacement`: `$4`
+* `os_v4_replacement`: `$5`
+
+In case that no matching `regex` is found the value for `os` shall be “Other”. The version information `major`, `minor`, `patch` and `patchMinor` shall not be defined.
+
+**Example:**
+
+For the User-Agent: `Mozilla/5.0 (Windows; U; Win95; en-US; rv:1.1) Gecko/20020826`
+the matching `regex`:
+
+```
+  - regex: 'Win(95|98|3.1|NT|ME|2000)'
+    os_replacement: 'Windows $1'
+```
+
+resolves to:
+
+```
+  os: Windows 95
+```
+
+## `device_parsers`
+
+The `device_parsers` return information of the device `family` the User-Agent runs on.
+Furthermore `brand` and `model` of the device can be specified.
+`brand` names the manufacturer of the device, where model specifies the model of the device.
+
+| match in regex | default replacement | placeholder in replacement | note   |
+| ---- | ------------------ | ------- | ---------------------------------------- |
+| 1    | device_replacement | $1...$9 | specifies the device family              |
+| any  | brand_replacement  | $1...$9 | major version number/info of OS          |
+| 1    | model_replacement  | $1...$9 | minor version number/info of the OS      |
+
+In case that no replacement is specified the association is given by order of the match.
+If in the `regex` no first match (within normal brackets) is given the `device_replacement` together with the `model_replacement` shall be specified!
+To overwrite the respective value the replacement value needs to be named for a given `regex`.
+
+For the `device_parsers` some `regex` require case insensitive parsing for proper matching. (E.g. Generic Feature Phones). To distinguish this from the case sensitive default case, the value `regex_flag: 'i'` is used to indicate that the regular-expression matching shall be case-insensitive for this regular expression.
+
+**Parser Implementation:**
+
+The list of regular-expressions `regex` shall be evaluated for a given user-agent string beginning with the first `regex`-item in the list to the last item. The first matching `regex` stops processing the list. Regex-matching shall be case sensitive.
+
+In case that no replacement for a match is given, the first match defines the `family` and the `model`.
+If a `*_replacement` string is specified it shall overwrite or replace the match.
+
+As placeholder for inserting matched characters `$1` to `$9` can be used to insert the matched characters from the regex into the replacement string.
+
+In case that no matching `regex` is found the value for `family` shall be “Other”. `brand` and `model` shall not be defined.
+Leading and tailing whitespaces shall be trimmed from the result.
+
+**Example:**
+
+For the User-Agent: `Mozilla/5.0 (Linux; U; Android 4.2.2; de-de; PEDI_PLUS_W Build/JDQ39) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30`
+the matching `regex`:
+
+```
+  - regex: '; *(PEDI)_(PLUS)_(W) Build'
+    device_replacement: 'Odys $1 $2 $3'
+    brand_replacement: 'Odys'
+    model_replacement: '$1 $2 $3'
+```
+
+resolves to:
+
+```
+  family: 'Odys PEDI PLUS W'
+  brand: 'Odys'
+  model: 'PEDI PLUS W'
+```
+
+# Parser Output
+
+To allow interoperability with code that builds upon ua-parser, it is recommended to provide the parser output in a standardized way. The structure defined in [WebIDL](http://www.w3.org/TR/WebIDL/) may follow:
+
+```
+interface ua-parser-output {
+  attribute string string;      // The "user-agent" string
+  object ua: {                  // The "user_agent_parsers" result
+    attribute string family;
+    attribute string major;
+    attribute string minor;
+    attribute string patch;
+  };
+  object os: {                 	// The "os_parsers" result
+    attribute string family;
+    attribute string major;
+    attribute string minor;
+    attribute string patch;
+    attribute string patchMinor;
+  };
+  object device: {              // The "device_parsers" result
+    attribute string family;
+    attribute string brand;
+    attribute string model;
+  };
+};
+```
diff --git a/package.json b/package.json
@@ -0,0 +1,35 @@
+{
+  "name": "uap-core",
+  "description": "The regex file necessary to build language ports of Browserscope's user agent parser.",
+  "version": "0.4.0",
+  "maintainers": [
+    {
+      "name": "Tobie Langel",
+      "email": "[email protected]",
+      "web": "http://tobielangel.com"
+    },
+    {
+      "name": "Lindsey Simon",
+      "email": "[email protected]",
+      "web": "http://www.idreamofuni.com"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "http://github.com/ua-parser/uap-core.git"
+  },
+  "licenses": [
+    {
+      "type": "Apache-2.0",
+      "url": "https://raw.github.com/ua-parser/uap-core/master/LICENSE"
+    }
+  ],
+  "devDependencies": {
+    "yamlparser": ">=0.0.2",
+    "mocha": "*",
+	"uap-ref-impl": "*"
+  },
+  "scripts": {
+    "test": "mocha -u tdd -R min ./tests/test.js"
+  }
+}