Finish 0.9.9

Author: khorevaa

.gitignore

@@ -1,2 +1,5 @@
 *.ospx
 tests.xml
+coverage/*
+
+tests-reports/*

.travis.yml

@@ -1,57 +1,85 @@
 sudo: required
-
-dist: trusty
+language: generic
 
 notifications:
   email: false
+env:
+  global:
+  - CHANNEL=dev
+  - PACKAGE_NAME=cli
+  matrix:
+  - OSCRIPT_VERSION=1_0_20
+  - OSCRIPT_VERSION=night-build
+matrix:
+  allow_failures:
+    - env: OSCRIPT_VERSION=night-build
+
+services:
+  - docker
+
+addons:
+    sonarqube: true
 
-before_install: 
-  - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
-  - echo "deb http://download.mono-project.com/repo/ubuntu trusty main" | sudo tee /etc/apt/sources.list.d/mono-official.list
-  - sudo apt-get update
-  - sudo apt-get install mono-complete mono-devel
-  - wget -O os.deb http://oscript.io/downloads/1_0_18/onescript-engine_1.0.18_all.deb
-  - sudo dpkg -i *.deb; sudo apt install -f
-  - sudo opm install opm@0.12.1
+jdk:
+  - oraclejdk8
+
+before_install:
+ # Load cached docker images
+  - if [[ -d $HOME/docker ]]; then ls $HOME/docker/*.tar.gz | xargs -I {file} sh -c "zcat {file} | docker load"; fi
+
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+
+after_script:
+  - ./cc-test-reporter after-build --prefix "/home/travis/build/khorevaa/cli/coverage/" --exit-code $TRAVIS_TEST_RESULT
+
+before_cache: 
+  # Save tagged docker images
+  - >
+    mkdir -p $HOME/docker && docker images -a --filter='dangling=false' --format '{{.Repository}}:{{.Tag}} {{.ID}}'
+    | xargs -n 2 -t sh -c 'test -e $HOME/docker/$1.tar.gz || docker save $0 | gzip -2 > $HOME/docker/$1.tar.gz'
 
 install: 
-  - sudo opm install 1testrunner
-  - sudo opm install 1bdd
-  - sudo opm install
+    - docker pull evilbeaver/onescript:1.0.19
 
-env:
-  global:
-  - CHANNEL=dev
+script:  
+  - docker version
+  - docker run -it -e OSCRIPT_VERSION=$OSCRIPT_VERSION -v $(pwd):/work_dir evilbeaver/onescript:1.0.19 sh -c 'cd /work_dir; sh /work_dir/travis-ci.sh; exit' | tee /tmp/test.log
+  - grep 'Результат прогона тестов <Да>' /tmp/test.log
+after_success:
+ # - bash <(curl -s https://codecov.io/bash)
+ # - ./sonar-qube.sh
 
 cache:
   directories:
     - '$HOME/.m2/repository'
     - '$HOME/.sonar/cache'
+    - '$HOME/docker'
 jobs:
   include:
-    - stage: Тестирование 
-      script: opm test
     - stage: Сборка и публикация github & hub.oscript.io
       script: skip 
       before_deploy:
-        - opm build ./
+        - docker run -it -v $(pwd):/work_dir evilbeaver/onescript:1.0.19 sh -c 'cd /work_dir; opm build ./ ; exit'
       deploy:
         - provider: releases
           api_key: "$GITHUB_OAUTH_TOKEN"
           file_glob: true
-          file: cli*.ospx
+          file: $PACKAGE_NAME*.ospx
           skip_cleanup: true
           on:
             branch: master
             tags: true
         - provider: script
           skip_cleanup: true
-          script: opm push --token $GITHUB_OAUTH_TOKEN --channel dev --file ./cli-*.ospx;
+          script: docker run -it -v $(pwd):/work_dir evilbeaver/onescript:1.0.19 sh -c 'cd /work_dir; opm push --token $GITHUB_OAUTH_TOKEN --channel dev --file ./$PACKAGE_NAME-*.ospx; exit'
           on:
             branch: develop
         - provider: script
           skip_cleanup: true
-          script: opm push --token $GITHUB_OAUTH_TOKEN --channel stable --file ./cli-*.ospx;
+          script: docker run -it -v $(pwd):/work_dir evilbeaver/onescript:1.0.19 sh -c 'cd /work_dir; opm push --token $GITHUB_OAUTH_TOKEN --channel stable --file ./$PACKAGE_NAME-*.ospx; exit'
           on:
             branch: master
             tags: true

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Используйте IntelliSense, чтобы узнать о возможных атрибутах.
+    // Наведите указатель мыши, чтобы просмотреть описания существующих атрибутов.
+    // Для получения дополнительной информации посетите: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Отладка 1Script",
+            "type": "oscript",
+            "request": "launch",
+            "program": "${file}",
+            "args": [],
+            "cwd": "${workspaceRoot}",
+            "runtimeExecutable": "/usr/bin/oscript",
+            "debugPort": 2801,
+            "protocol": "internal"
+        }
+    ]
+}

ISSUE_TEMPLATE.md

@@ -1 +1 @@
-Просто создавайте запросы на измнения или ошибки!
+Просто создавайте запросы на изменения или ошибки!

README.md

@@ -1,4 +1,4 @@
-# cli
+# `C`_ommand_ `L`_ine_ `I`_nterface_ для OScript
 
 [![Stars](https://img.shields.io/github/stars/khorevaa/cli.svg?label=Github%20%E2%98%85&a)](https://github.com/khorevaa/cli/stargazers)
 [![Release](https://img.shields.io/github/tag/khorevaa/cli.svg?label=Last%20release&a)](https://github.com/khorevaa/cli/releases)
@@ -7,6 +7,7 @@
 [![Build Status](https://travis-ci.org/khorevaa/cli.svg?branch=master)](https://travis-ci.org/khorevaa/cli)
 [![Coverage Status](https://coveralls.io/repos/github/khorevaa/cli/badge.svg?branch=master)](https://coveralls.io/github/khorevaa/cli?branch=master)
 
+Короткое название библиотеки `cli`
 
 Данная библиотека для языка OScript, позволяет создавать консольные приложения с разбором и проверкой аргументов.
 
@@ -52,7 +53,7 @@
 КонецПопытки;
 ```
 
-### Пример приложения с несколькими командами:
+### Пример приложения с несколькими командами
 
 ```bsl
 #Использовать cli
@@ -84,6 +85,57 @@
 КонецПопытки;
 ```
 
+### Пример приложения с вложенными командами
+
+```bsl
+#Использовать cli
+
+///////////////////////////////////////////////////////////////////////////////
+
+Процедура ВыполнитьПриложение()
+
+    Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli");
+    Приложение.Версия("v version","1.0.0");
+
+    Приложение.ДобавитьКоманду("i init", "Инициализация структуры нового приложения", Новый КомандаInit);
+    Приложение.ДобавитьКоманду("g generate", "Генерация элементов структуры приложения", Новый КомандаGenerate);
+
+    Приложение.Запустить(АргументыКоманднойСтроки);
+
+КонецПроцедуры // ВыполнениеКоманды()
+
+///////////////////////////////////////////////////////
+
+Попытка
+
+    ВыполнитьПриложение();
+
+Исключение
+
+    Сообщить(ОписаниеОшибки());
+
+КонецПопытки;
+
+```
+Класс `КомандаGenerate`
+Для добавления подкоманды в любую команду используются методы `ДобавитьПодкоманду` или `ДобавитьКоманду`
+
+```bsl
+
+Процедура ОписаниеКоманды(Команда) Экспорт
+
+    // Метод <ДобавитьПодкоманду>
+    Команда.ДобавитьПодкоманду("c command", "Генерация дополнительной вложенной команды", Новый КомандаGenerateCommand);
+    
+    // Метод <ДобавитьКоманду>
+    Команда.ДобавитьКоманду("o option", "Генерация опции для команды", Новый КомандаGeneratOption);
+
+Процедура ВыполнитьКоманду(Знач Команда) Экспорт
+
+КонецПроцедуры
+
+```
+
 ## Мотивация
 
 Для PR в cmdline слишком большие изменения в API, т.е. обеспечить совместимость очень трудоемко.
@@ -116,6 +168,10 @@
 $ opm install -f <ПутьКФайлу>
 ```
 
+Либо, скачать библиотеку с помощью opm:
+
+    opm install cli
+
 ## Базовые принципы
 
 При создании приложения необходимо указать имя приложения и описание:
@@ -124,35 +180,52 @@ $ opm install -f <ПутьКФайлу>
 Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli");
 ```
 
-Для установки основной функции выполнения приложения необходимо создать класс, или сам модуль должен реализовать экспортную процедуру:
+Каждый возможный вариант выполнения - это "Команда". Команды могут создаваться явно, кроме того, само Приложение содержит в себе корневую (Основную) команду.
+
+Каждая команда реализуется в виде отдельного класса. Каждый такой класс обязан иметь экспортную процедуру
+
 ```bsl
 Процедура ВыполнитьКоманду(Знач Команда) Экспорт
 КонецПроцедуры
 ```
+
+Для установки основной функции выполнения приложения в приложении надо установить основное действие. В простейшем случае основным действием может выступать сам стартовый сценарий:
+
 Передать данный класс через процедуру:
 ```bsl
 Приложение.УстановитьОсновноеДействие(ЭтотОбъект)
 ```
 
+### Встроенная команда "Версия"
 
 Для добавления отображения версии через опции: ```-v, --version``` надо добавить строчку:
 
 ```bsl
 Приложение.Версия("v version", "1.2.3");
 ```
 
+Это позволит запускать приложение с ключом ``v`` или ``--version``:
+
+    my-app --version
+
+### Запуск парсера аргументов и приложения в целом
+
 Для запуска приложения необходимо добавить строчку:
 
 ```bsl
 Приложение.Запустить(АргументыКоманднойСтроки);
 ```
 
+Этот вызов является "точкой входа" в консольное приложение. В общем случае, после него уже не идет никакого дополнительного кода. Парсер анализирует аргументы и запускает команды автоматически.
+
 ## Параметры команд/приложения
 
 Все параметры разделяются на два типа:
 * Опция 
 * Аргумент
 
+В общем случае, Опции имеют имена, аргументы являются позиционными. Кроме того, по умолчанию указание опций необязательно, а аргументов - обязательно. Это можно переопределить, но дефолтное поведение именно такое. Аргумент - обязателен, опция - нет.
+
 ## Опция
 
 Опция может быть следующих простых типов:
@@ -346,7 +419,7 @@ cli поддерживает автоматическую инициализац
 
 ## Строка использования приложения (спек)
 
-Синтаксис спек базируется на POSIX.
+Синтаксис спек базируется на POSIX. Спек является грамматикой парсера аргументов и определяет порядок следования аргументов и опций в командной строке, а также вариативность параметров. Спек формируется либо вручную через указание в поле `Спек`, либо автоматически в момент вызова выполнения приложения / или команды.
 
 ### Опции
 
@@ -375,7 +448,7 @@ cli поддерживает автоматическую инициализац
 
 Пример добавления аргументов в команду:
 
-```go
+```bsl
 Команда.Аргумент("SRC", ...);
 Команда.Аргумент("DST", ...);
 ```
@@ -388,6 +461,8 @@ cli позволяет произвольно настраивать поряд
 Команда.Спек = "-f -g NAME -h PATH";
 ```
 
+В примере выше задана грамматика: в командой строке могут идти сначала опции -f и -g, затем аргумент NAME, затем опция -h, затем аргумент PATH.
+
 ## Необязательность
 
 Для того, чтобы сделать аргументы или опции необязательными, их необходимо заключить в `[...]`:

appveyor.yml

@@ -0,0 +1,63 @@
+version: 0.9.8-{build}
+pull_requests:
+  do_not_increment_build_number: true
+max_jobs: 1
+init:
+- ps: Set-WinSystemLocale ru-RU
+
+#environment:
+#  oscript: C:\Program Files (x86)\OneScript\bin\oscript.exe
+
+install:
+- cmd: >-
+    @echo on
+    # git submodule update --init --recursive
+    set
+
+    curl -o %temp%\oscript-setup.exe http://oscript.io/downloads/latest/exe
+
+    %temp%\oscript-setup.exe /silent /log="%temp%\oscript-setup.log" /saveinf="%temp%\oscript-setup-settings.txt"
+
+    set OSCRIPT=%ProgramFiles(x86)%\OneScript
+
+    dir "%OSCRIPT%\bin"
+    dir "%OSCRIPT%\lib"
+
+    rem SET PATH=%CD%\engine\bin;%PATH%
+
+    SET PATH=%OSCRIPT%\bin;%PATH%
+
+    where oscript
+    
+    oscript -version
+    
+    chcp 65001
+
+    opm install opm
+    
+    opm install 1testrunner 
+    
+    opm install 1bdd
+    
+    opm install coverage 
+
+    
+    opm install
+    
+    opm list
+# to disable automatic builds
+build: off
+test_script:
+- cmd: >-
+    
+    opm run coverage
+    
+    pushd %APPVEYOR_BUILD_FOLDER%
+
+after_test:
+- ps: # upload results to AppVeyor
+- ps: Write-Host "Загружаю результаты тестов на CI"
+- ps: $wc = New-Object 'System.Net.WebClient'
+- ps: $wc.UploadFile("https://ci.appveyor.com/api/testresults/junit/$($env:APPVEYOR_JOB_ID)", (Resolve-Path .\tests-reports\tests.xml))
+artifacts:
+- path: tests-reports\tests.xml