Espruino:Примеры/Создание и подача на рассмотрение модулей (или изменений в них): различия между версиями
Myagkij (обсуждение | вклад) Нет описания правки |
Myagkij (обсуждение | вклад) Нет описания правки |
||
Строка 5: | Строка 5: | ||
=Создание и подача на рассмотрение модулей (или изменений в них)<ref>[https://www.espruino.com/Writing+Modules www.espruino.com - Writing and Submitting Modules (or changes)]</ref>= | =Создание и подача на рассмотрение модулей (или изменений в них)<ref>[https://www.espruino.com/Writing+Modules www.espruino.com - Writing and Submitting Modules (or changes)]</ref>= | ||
Если вы разработали код для взаимодействия с каким-то устройством (например, с LCD-дисплеем или каким-то аппаратным модулем), было бы здорово, если бы вы также создали и подали на рассмотрение JavaScript-модуль (библиотеку), которой могли бы воспользоваться другие люди при помощи команды вроде require("libname"). | Если вы разработали код для взаимодействия с каким-то устройством (например, с [[LCD-дисплеем]] или каким-то аппаратным модулем), было бы здорово, если бы вы также создали и подали на рассмотрение JavaScript-модуль (библиотеку), которой могли бы воспользоваться другие люди при помощи команды вроде '''require("libname")'''. | ||
* Создайте аккаунт в [https://github.com/ GitHub]. | * Создайте аккаунт в [https://github.com/ GitHub]. | ||
* Зайдите [https://github.com/espruino/EspruinoDocs сюда] и кликните на кнопку Fork справа вверху. В результате на вашем GitHub-аккаунте появится полная копия всей документации этого репозитория. | * Зайдите [https://github.com/espruino/EspruinoDocs сюда] и кликните на кнопку Fork справа вверху. В результате на вашем GitHub-аккаунте появится полная копия всей документации этого репозитория. | ||
* Кликните на папку «devices», затем на Add file > Create new file справа вверху. | * Кликните на папку ''«devices»'', затем на '''Add file > Create new file''' справа вверху. | ||
* Назовите свой модуль в честь устройства, для которого разработан ваш код (но постарайтесь, чтобы название было как можно короче – как | * Назовите свой модуль в честь устройства, для которого разработан ваш код (но постарайтесь, чтобы название было как можно короче – как ''«[[PCD8544]]»'' для чипа, управляющего работой [[LCD-дисплея]] [[Nokia]]), а в конце добавьте ''«[[.js]]»''. В результате у вас должно получиться что-то вроде ''«MOD123.js»''. | ||
<syntaxhighlight lang="javascript" enclose="div"> | <syntaxhighlight lang="javascript" enclose="div"> | ||
Строка 56: | Строка 56: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Чтобы протестировать свой модуль, скопируйте его полностью в правую часть Web IDE, но в самом верху у него должна быть строчка var exports={};. А внизу (там, где используете модуль) напишите var exports={} вместо require('MOD123').myfunction(). | Чтобы протестировать свой модуль, скопируйте его полностью в правую часть [[Web IDE]], но в самом верху у него должна быть строчка '''var exports={};'''. А внизу (там, где используете модуль) напишите '''var exports={}''' вместо '''require('MOD123').myfunction()'''. | ||
В качестве примера можете взглянуть на [http://www.espruino.com/modules/ уже готовые модули] (некоторые из них шаблону выше не следуют). Вот пара важных вещей, которые помогут сделать ваш модуль эффективнее: | В качестве примера можете взглянуть на [http://www.espruino.com/modules/ уже готовые модули] (некоторые из них шаблону выше не следуют). Вот пара важных вещей, которые помогут сделать ваш модуль эффективнее: | ||
* После загрузки модуля Espruino выполняет файл в его собственной области видимости, а затем сохраняет переменные и функции, которые были заданы в этой области видимости, в кэш модулей. | * После загрузки модуля [[Espruino]] выполняет файл в его собственной области видимости, а затем сохраняет переменные и функции, которые были заданы в этой области видимости, в кэш модулей. | ||
* Все функции и переменные, которые были заданы в корневой области видимости, будут общими и не будут дублироваться, если модуль будет использован в коде дважды. Но если вы зададите функцию внутри другой функции (например, внутри функции exports.myfunction) то эта функция будет создаваться снова при каждом вызове функции exports.myfunction. | * Все функции и переменные, которые были заданы в корневой области видимости, будут общими и не будут дублироваться, если модуль будет использован в коде дважды. Но если вы зададите функцию внутри другой функции (например, внутри функции '''exports.myfunction''') то эта функция будет создаваться снова при каждом вызове функции '''exports.myfunction'''. | ||
* Большинство пользователей используют require() и в этом случае Web IDE загрузит минимизированную версию модуля. Это значит, что... | * Большинство пользователей используют [[require()]] и в этом случае [[Web IDE]] загрузит минимизированную версию модуля. Это значит, что... | ||
** ...все непубличные константы и функции будут минифицированы, если в этом будет смысл. Это сэкономит место и сделает библиотеку быстрее. | ** ...все непубличные константы и функции будут минифицированы, если в этом будет смысл. Это сэкономит место и сделает библиотеку быстрее. | ||
** ...все комментарии будут удалены. | ** ...все комментарии будут удалены. | ||
* Даже если пользователь не использует минимизированную версию (возможно, он скопировал на карту Micro-SD полную версию или поменял настройки Web IDE): | * Даже если пользователь не использует минимизированную версию (возможно, он скопировал на карту [[Micro-SD]] полную версию или поменял настройки [[Web IDE]]): | ||
** Espruino сохранит содержимое функций полностью (включая комментарии), но комментарии, находящиеся за пределами объявления функции, места занимать не будут. | ** [[Espruino]] сохранит содержимое функций полностью (включая комментарии), но комментарии, находящиеся за пределами объявления функции, места занимать не будут. | ||
* Кликните на кнопку Commit new file внизу. Если вы захотите что-то поменять, вы всегда сможете снова кликнуть на этот файл, а затем кликнуть на иконку с карандашом справа вверху, чтобы начать редактирование этого файла. | * Кликните на кнопку '''Commit new file''' внизу. Если вы захотите что-то поменять, вы всегда сможете снова кликнуть на этот файл, а затем кликнуть на иконку с карандашом справа вверху, чтобы начать редактирование этого файла. | ||
* Теперь нам нужно создать маленький файл для документации, чтобы ваш модуль смогли найти другие пользователи. Добавьте ещё один файл и назовите его «MOD123.md». | * Теперь нам нужно создать маленький файл для документации, чтобы ваш модуль смогли найти другие пользователи. Добавьте ещё один файл и назовите его ''«MOD123.md»''. | ||
* Скопируйте в него шаблон ниже (первым словом в строчке KEYWORDS всегда должно стоять слово Module). | * Скопируйте в него шаблон ниже (первым словом в строчке '''KEYWORDS''' всегда должно стоять слово '''Module'''). | ||
<syntaxhighlight lang="javascript" enclose="div"> | <syntaxhighlight lang="javascript" enclose="div"> | ||
Строка 99: | Строка 99: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Описание модуля нужно будет отформатировать при помощи языка разметки Markdown. Примеры его использования ищите [https://docs.github.com/en/github/writing-on-github здесь] или у других модулей на GitHub. | Описание модуля нужно будет отформатировать при помощи языка разметки '''Markdown'''. Примеры его использования ищите [https://docs.github.com/en/github/writing-on-github здесь] или у других модулей на GitHub. | ||
Кроме того, если у вашего модуля больше одной функции, вы можете добавить в него APPEND_JSDOC. Это просканирует указанный JS-файл (то есть в данном случае – MOD123.js) на предмет экспортированных функций и комментариев в формате /** ... */, чтобы потом добавить их в ваш модуль в качестве справочной информации. | Кроме того, если у вашего модуля больше одной функции, вы можете добавить в него '''APPEND_JSDOC'''. Это просканирует указанный JS-файл (то есть в данном случае – '''MOD123.js''') на предмет экспортированных функций и комментариев в формате '''/** ... */''', чтобы потом добавить их в ваш модуль в качестве справочной информации. | ||
<syntaxhighlight lang="javascript" enclose="div"> | <syntaxhighlight lang="javascript" enclose="div"> | ||
Строка 109: | Строка 109: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Кроме того, вы можете добавить в него APPEND_USES. Теперь если у какого-то [https://www.espruino.com/Writing+Tutorials руководства] вверху будет написано USES: MOD123, то он будет указан на странице вашего модуля: | Кроме того, вы можете добавить в него '''APPEND_USES'''. Теперь если у какого-то [https://www.espruino.com/Writing+Tutorials руководства] вверху будет написано '''USES: MOD123''', то он будет указан на странице вашего модуля: | ||
<syntaxhighlight lang="javascript" enclose="div"> | <syntaxhighlight lang="javascript" enclose="div"> | ||
Строка 116: | Строка 116: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* APPEND_USES: MOD123 | * '''APPEND_USES: MOD123''' | ||
* Вот и всё! Теперь кликните на кнопку Commit New File внизу. | * Вот и всё! Теперь кликните на кнопку '''Commit New File''' внизу. | ||
* При необходимости внесите нужные правки и изменения, а затем кликните на кнопку Pull Request справа вверху. | * При необходимости внесите нужные правки и изменения, а затем кликните на кнопку '''Pull Request''' справа вверху. | ||
* Проверьте, правильные ли файлы там показаны (это должны быть файлы, которые мы создали в этом руководстве), а затем кликните на Create pull request. | * Проверьте, правильные ли файлы там показаны (это должны быть файлы, которые мы создали в этом руководстве), а затем кликните на '''Create pull request'''. | ||
* Откроется новая страница, где надо будет ввести название и описание пулл-реквеста. Указав их, нажмите на Create pull request. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным. | * Откроется новая страница, где надо будет ввести название и описание пулл-реквеста. Указав их, нажмите на '''Create pull request'''. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным. | ||
=См.также= | =См.также= |
Версия от 18:15, 14 июля 2021
Создание и подача на рассмотрение модулей (или изменений в них)[1]
Если вы разработали код для взаимодействия с каким-то устройством (например, с LCD-дисплеем или каким-то аппаратным модулем), было бы здорово, если бы вы также создали и подали на рассмотрение JavaScript-модуль (библиотеку), которой могли бы воспользоваться другие люди при помощи команды вроде require("libname").
- Создайте аккаунт в GitHub.
- Зайдите сюда и кликните на кнопку Fork справа вверху. В результате на вашем GitHub-аккаунте появится полная копия всей документации этого репозитория.
- Кликните на папку «devices», затем на Add file > Create new file справа вверху.
- Назовите свой модуль в честь устройства, для которого разработан ваш код (но постарайтесь, чтобы название было как можно короче – как «PCD8544» для чипа, управляющего работой LCD-дисплея Nokia), а в конце добавьте «.js». В результате у вас должно получиться что-то вроде «MOD123.js».
* Скопируйте в этот файл вот этот шаблон:
/* Copyright (c) 2014 Ваше имя.
Информацию о лицензии скопируйте из файла LICENSE. */
/*
Краткое описание вашего модуля...
*/
var C = {
MY : 0x001, // описание
PRIVATE : 0x001, // описание
CONSTANTS : 0x00423 // описание
};
function MOD123(pin1,pin2) {
this.pin1 = pin1;
this.pin2 = pin2;
}
/** Здесь будут «публичные» константы */
MOD123.prototype.C = {
MY : 0x013, // описание
PUBLIC : 0x0541, // описание
CONSTANTS : 0x023 // описание
};
/** Большинство комментариев должны стоять вне функций... */
MOD123.prototype.foo = function() {
// вы можете использовать C.PRIVATE
// или this.C.PUBLIC
};
/** Большинство комментариев должны стоять вне функций... */
MOD123.prototype.bar = function() {
};
/** Это «экспортированная» функция,
так что вы можете использовать её при помощи
`require('MOD123.js').connect(pin1,pin2)` */
exports.connect = function (pin1, pin2) {
return new MOD123(pin1, pin2);
};
Чтобы протестировать свой модуль, скопируйте его полностью в правую часть Web IDE, но в самом верху у него должна быть строчка var exports={};. А внизу (там, где используете модуль) напишите var exports={} вместо require('MOD123').myfunction().
В качестве примера можете взглянуть на уже готовые модули (некоторые из них шаблону выше не следуют). Вот пара важных вещей, которые помогут сделать ваш модуль эффективнее:
- После загрузки модуля Espruino выполняет файл в его собственной области видимости, а затем сохраняет переменные и функции, которые были заданы в этой области видимости, в кэш модулей.
- Все функции и переменные, которые были заданы в корневой области видимости, будут общими и не будут дублироваться, если модуль будет использован в коде дважды. Но если вы зададите функцию внутри другой функции (например, внутри функции exports.myfunction) то эта функция будет создаваться снова при каждом вызове функции exports.myfunction.
- Большинство пользователей используют require() и в этом случае Web IDE загрузит минимизированную версию модуля. Это значит, что...
- ...все непубличные константы и функции будут минифицированы, если в этом будет смысл. Это сэкономит место и сделает библиотеку быстрее.
- ...все комментарии будут удалены.
- Даже если пользователь не использует минимизированную версию (возможно, он скопировал на карту Micro-SD полную версию или поменял настройки Web IDE):
- Espruino сохранит содержимое функций полностью (включая комментарии), но комментарии, находящиеся за пределами объявления функции, места занимать не будут.
- Кликните на кнопку Commit new file внизу. Если вы захотите что-то поменять, вы всегда сможете снова кликнуть на этот файл, а затем кликнуть на иконку с карандашом справа вверху, чтобы начать редактирование этого файла.
- Теперь нам нужно создать маленький файл для документации, чтобы ваш модуль смогли найти другие пользователи. Добавьте ещё один файл и назовите его «MOD123.md».
- Скопируйте в него шаблон ниже (первым словом в строчке KEYWORDS всегда должно стоять слово Module).
<!--- Copyright (c) 2014 Ваше имя.
Информацию о лицензии смотрите в файле LICENSE. -->
Формальное название вашего модуля.
=====================
* KEYWORDS: Module,список,слов,для,поиска,модуля,разделенных,запятой
Немного информации о модуле. Здесь можно, например,
немного описать устройство, для которого разработан этот модуль.
Устройство можно подключить следующим образом:
| Контакт | Espruino |
| Устройства | |
| ---------- | -------- |
| 1 (GND) | GND |
| 2 (VCC) | 3.3 |
| 3 (SIGIN) | A0 |
| 4 (SIGNOUT)| A1 |
Как использовать мой модуль:
```
var foo = require("MOD123").connect(A0,A1);
foo.usingFoo();
```
Описание модуля нужно будет отформатировать при помощи языка разметки Markdown. Примеры его использования ищите здесь или у других модулей на GitHub. Кроме того, если у вашего модуля больше одной функции, вы можете добавить в него APPEND_JSDOC. Это просканирует указанный JS-файл (то есть в данном случае – MOD123.js) на предмет экспортированных функций и комментариев в формате /** ... */, чтобы потом добавить их в ваш модуль в качестве справочной информации.
Reference
---------
* APPEND_JSDOC: MOD123.js
Кроме того, вы можете добавить в него APPEND_USES. Теперь если у какого-то руководства вверху будет написано USES: MOD123, то он будет указан на странице вашего модуля:
Using
-----
- APPEND_USES: MOD123
- Вот и всё! Теперь кликните на кнопку Commit New File внизу.
- При необходимости внесите нужные правки и изменения, а затем кликните на кнопку Pull Request справа вверху.
- Проверьте, правильные ли файлы там показаны (это должны быть файлы, которые мы создали в этом руководстве), а затем кликните на Create pull request.
- Откроется новая страница, где надо будет ввести название и описание пулл-реквеста. Указав их, нажмите на Create pull request. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным.
См.также
Внешние ссылки