Neprogramátor/Čarodějnické řemeslo: zdrojové kódy a repozitář
K psaní dopisu pro kouzelnou hůlku používá čaroděj (textový) editor. Většinou je to ale trochu vylepšený editor, který dokáže zvýraznit slovesa či podstatná jména kouzelného jazyka a dost často je v něm zakomponovaná i kouzelná hůlka. Takovému editoru se říká vývojové prostředí, kterým je třeba i DrRacket.
Práce čaroděje-spisovatele je napsat hezký dopis. Kouzelná hůlka hezký dopis moc neocení, zato další čarodějové a čarodějky pracující na podobných problémech ano. Dopis pro kouzelnou hůlku, kterému se říká zdrojový kód, popisuje, jak vyřešit nějaký problém. Když chce čaroděj sdílet své řešení problému s ostatními, jednoduše pošle svůj dopis pro kouzelnou hůlku i jim. Ostatním čarodějům a čarodějkám se také hodí vědět, co za problém se vlastně řeší a proč. K tomu slouží dobrá jména kouzelných sloves a kouzelných podstatných jmen a také doprovodný text, kterému se říká dokumentace. A nakonec, pro spolupráci s ostatními čaroději je dobré vědět, jak dopis pro kouzelnou hůlku vznikl. Nejznámější program, který se na průběžné sledování změn v dopise pro kouzelnou hůlku používá, je Git.
Dopis pro kouzelnou hůlku se napíše v DrRacket, uloží se do souboru v adresáři (občas někdo adresáři říká složka) a v tomhle adresáři se použije příkaz git, pomocí kterého se sledují změny v dopise pro kouzelnou hůlku. Adresáři, ve kterém se použije příkaz git, se říká repozitář.
Takže:
- DrRacket je vývojové prostředí pro psaní zdrojových kódu v programovacím jazyce Racket.
- Git je program, který slouží pro sledování historie adresáře s textovými soubory. Adresáři se říká repozitář.
- Kombinace DrRacket a Git se s výhodou použije pro zaznamenání vývoje řešení problému.
Je větší 20 nebo číslo?[editovat | editovat zdroj]
Takovým problémem může být například:
Podstatné jméno (číslo) 20 je pojmenované jako dvacet a nové kouzelné sloveso větší-než pracuje s jedním podstatným jménem (parametrem) číslo: jestli je číslo větší než dvacet, kouzelné sloveso větší-než vrátí nové podstatné jméno (text) "Větší je číslo.", kde číslo v textu je nahrazené konkrétní aktuální hodnotou; jinak vrátí "Větší je 20.".
Řešením takového problému třeba:
; Je větší 20 nebo číslo?
(define dvacet 20)
(define (větší-než číslo)
(if (> číslo dvacet)
(string-append "Větší je " (number->string číslo) ".")
(string-append "Větší je " (number->string dvacet) ".")))
(větší-než 11)
(větší-než 27)
Výsledek je potom:
"Větší je 20." "Větší je 27."
A postup řešení:
$ git log
commit c25ad0493e6d4d51d789da51055014def4ae7bb1 (HEAD -> master)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sun Jan 21 00:19:39 2024 +0100
Přidej řešení "Je větší 20 nebo číslo?"
commit 8af19a8bafa550e7f8f49770e3d230a114b26d6c
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sat Jan 20 23:47:27 2024 +0100
Přidej licenci a readme
No a teď jak na to.
Instalace a nastavení Git[editovat | editovat zdroj]
Pro použití Git je potřeba Git stáhnout, nainstalovat a nastavit. Po instalaci jde Git spustit: v Linux příkazem git v příkazové řádce, ve Windows pak v příkazové řádce programu "Git Bash". Pro používání příkazu git je potřeba:
- Nastavit jméno čaroděje:
$ git config --global user.name "Jméno Čaroděje"
- Nastavit email čaroděje:
$ git config --global user.email "email@carodeje.xyz"
- Nastavit textový editor pro Windows:
$ git config --global core.editor "notepad"
a pro Linux třeba:
$ git config --global core.editor "gedit"
Vytvoření repozitáře[editovat | editovat zdroj]
Repozitář je adresář, ve kterém je soubor s dopisem pro kouzelnou hůlku. První krok k vytvoření repozitáře je proto vytvoření nového adresáře (složky), což jde udělat stejným způsobem, jakým se vytváří nové adresáře obvykle. Nebo přímo z DrRacket klávesovovou zkratkou Ctrl + S (nebo "File -> Save Definitions"). Na vhodném místě se potom vytvoří adresář větší-než a v něm soubor větší-než.rkt. (Obsah souboru je řešení problému, viz výše.)
Druhý krok k vytvoření repozitáře je příkaz git init. Když je Git nastavený a adresář větší-než vytvořený, je třeba se do adresáře větší-než přepnout (v Linux pomocí cd větší-než nebo ve Windows kliknout pravým tlačítkem na adresář větší-než a vybrat "Spustit Git Bash zde ...",) a konečně v adresáři větší-než napsat příkaz git init a zmáčknout klávesu [Enter]:
$ git init hint: Using 'master' as the name for the initial branch. This default branch name hint: is subject to change. To configure the initial branch name to use in all hint: of your new repositories, which will suppress this warning, call: hint: hint: git config --global init.defaultBranch <name> hint: hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and hint: 'development'. The just-created branch can be renamed via this command: hint: hint: git branch -m <name> Initialized empty Git repository in /cesta/k/větší-než/.git/
Příkazy programu Git vždy souvisí s repozitářem. V této wikiknize je vždy na začátku uvedeno, o jaký repozitář se jedná a všechny příkazy programu Git jsou pak spouštěny z odpovídajícího adresáře. Takže třeba pro repozitář větší-než je příkaz
$ git status
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
"v\304\233t\305\241\303\255-ne\305\276.rkt"
nothing added to commit but untracked files present (use "git add" to track)
spuštěný (v příkazové řádce) z adresáře větší-než. Příkaz git status zobrazí stav repozitáře a ve výpisu je vidět, že v adresáři je nový soubor a že git má trochu problémy s diakritikou.
Sledování změn souborů[editovat | editovat zdroj]
Jako první se do repozitáře přidávají dva soubory: LICENSE a README. Soubor LICENSE říká, za jakých podmínek můžou kouzelné věty použít ostatní čarodějové. Soubor README představuje repozitář: Co je pointa a proč zrovna to, jak s repozitářem pracovat a kam a komu napsat dotaz.
Soubory se připraví ke sledování jejich historie příkazem
$ git add LICENSE README
a aktuální stav repozitáře se zkontroluje příkazem
$ git status
On branch master
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: LICENSE
new file: README
Untracked files:
(use "git add <file>..." to include in what will be committed)
"v\304\233t\305\241\303\255-ne\305\276.rkt"
Příkaz git status ukáže tři skupiny souborů, ale každou ze skupin vynechá, když do ní nespadá žádný soubor:
- Zelené soubory připravené k zanesení do historie (changes to be committed).
- Červené změněné soubory, které ale nejsou připravené (changes not staged for commit).
- Červené soubory, které nikdy nebyly v historii (untracked files).
Z červeného udělám zelený tak, že
$ git add JMENO-SOUBORU
a naopak ze zeleného červený tak, že
$ git reset JMENO-SOUBORU
Z příkazu git status výše je vidět, že soubory LICENSE a README jsou připraveny k zanesení do historie repozitáře. Konečně k zanesení do historie repozitáře slouží příkaz:
$ git commit [master (root-commit) 5c514bd] Přidej licenci a readme 2 files changed, 30 insertions(+) create mode 100644 LICENSE create mode 100644 README
který otevře textový editor, počká na krátkou zprávu a po uložení zprávy a ukončení textového editoru přidá soubory LICENSE a README do historie repozitáře.
Krátká zpráva má svoje pravidla. První řádek je nadpis: začíná velkým písmenem, na konci NENÍ tečka, je maximálně 52 znaků dlouhý a je v rozkazovacím způsobu. První řádek říká, co se do historie repozitáře ukládá. Krátká zpráva "Přidej licenci a readme" je celkem dobrá ukázka, jak může první řádek vypadat.
Pokud je potřeba rozvést co nebo proč se ukládá do historie repozitáře, za prvním řádkem následuje jeden prázdný řádek a pak odstavce, které to co a proč rozvedou. Ty už můžou být zarovnané na délku 72 znaků.
Psát jak se změny provedou je zbytečné, protože čarodějové přeci tráví dost času na tom, aby kouzelné věty, které píší, byly hezké. A jak se to co provede, je přece zapsáno právě v těch kouzelných větách!
Historie rezpozitáře[editovat | editovat zdroj]
Historie repozitáře se prohlíží příkazem
$ git log
commit 8af19a8bafa550e7f8f49770e3d230a114b26d6c (HEAD -> master)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sat Jan 20 23:47:27 2024 +0100
Přidej licenci a readme
Historie repozitáře sestává ze změn, kterým se říká commit. Lze zobrazit i jednotlivé změny (commit), což se dělá příkazem git show IDENTIFIKATOR-ULOZENE-ZMENY. Konkrétně například:
$ git show 8af19a8bafa550e7f8f49770e3d230a114b26d6c
commit 8af19a8bafa550e7f8f49770e3d230a114b26d6c (HEAD -> master)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sat Jan 20 23:47:27 2024 +0100
Přidej licenci a readme
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..54d1cf4
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2024 Jméno Čaroděje
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README b/README
new file mode 100644
index 0000000..95c0ddc
--- /dev/null
+++ b/README
@@ -0,0 +1,11 @@
+Je větší 20 nebo číslo?
+
+Jednoduché řešení následujícího problému:
+
+> Podstatné jméno (číslo) 20 je pojmenované jako dvacet a nové kouzelné sloveso
+> větší-než pracuje s jedním podstatným jménem (parametrem) číslo: jestli je
+> číslo větší než dvacet, kouzelné sloveso větší-než vrátí nové podstatné jméno
+> (text) "Větší je číslo.", kde číslo v textu je nahrazené konkrétní aktuální
+> hodnotou; jinak vrátí "Větší je 20.".
+
+Pro více informací: https://cs.wikibooks.org/wiki/Neprogram%C3%A1tor/%C4%8Carod%C4%9Bjnick%C3%A9_%C5%99emeslo:_zdrojov%C3%A9_k%C3%B3dy_a_repozit%C3%A1%C5%99
Z výpisu výše je vidět, že je použita permisivní MIT Licence. To znamená, že kouzelné věty může použít kdokoli a jakkoli za podmínky, že k nim vždy přidá text licence. Je hodně druhů licencí a hodně rad, jak licenci vybrat.
Sledování změn dalších souborů[editovat | editovat zdroj]
Příkaz
$ git status
On branch master
Untracked files:
(use "git add <file>..." to include in what will be committed)
"v\304\233t\305\241\303\255-ne\305\276.rkt"
nothing added to commit but untracked files present (use "git add" to track)
ukazuje, že v repozitáři je ještě jeden soubor ke sledování -- soubor s řešením problému. Teď už by mělo být jasné, jaké příkazy použít k připravení a zaznamenání souboru do historie repozitáře, k zobrazení historie repozitáře a k zobrazení samotné změny.
Které příkazy to jsou?
Pro připravení souboru k zaznamenání do historie repozitáře:
$ git add větší-než.rkt
Pro zaznamenání souboru do historie repozitáře:
$ git commit [master c25ad04] Přidej řešení "Je větší 20 nebo číslo?" 1 file changed, 9 insertions(+) create mode 100644 "v\304\233t\305\241\303\255-ne\305\276.rkt"
Pro zobrazení historie repozitáře:
$ git log
commit c25ad0493e6d4d51d789da51055014def4ae7bb1 (HEAD -> master)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sun Jan 21 00:19:39 2024 +0100
Přidej řešení "Je větší 20 nebo číslo?"
commit 8af19a8bafa550e7f8f49770e3d230a114b26d6c
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sat Jan 20 23:47:27 2024 +0100
Přidej licenci a readme
Pro zobrazení samotné změny:
$ git show c25ad0493e6d4d51d789da51055014def4ae7bb1
commit c25ad0493e6d4d51d789da51055014def4ae7bb1 (HEAD -> master)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Sun Jan 21 00:19:39 2024 +0100
Přidej řešení "Je větší 20 nebo číslo?"
diff --git "a/v\304\233t\305\241\303\255-ne\305\276.rkt" "b/v\304\233t\305\241\303\255-ne\305\276.rkt"
new file mode 100644
index 0000000..518323e
--- /dev/null
+++ "b/v\304\233t\305\241\303\255-ne\305\276.rkt"
@@ -0,0 +1,9 @@
+#lang racket
+; Je větší 20 nebo číslo?
+(define dvacet 20)
+(define (větší-než číslo)
+ (if (> číslo dvacet)
+ (string-append "Větší je " (number->string číslo) ".")
+ (string-append "Větší je " (number->string dvacet) ".")))
+(větší-než 11)
+(větší-než 27)
Přehled prvních příkazů Git[editovat | editovat zdroj]
První příkazy programu Git pomůžou s vytvořením repozitáře, sledováním souborů a jednoduchým zobrazením historie repozitáře.
Nastavení:
$ git config --global user.name "Jméno Čaroděje" $ git config --global user.email "email@carodeje.xyz".
Vytvoření repozitáře:
$ git init $ git status
Sledování změn souborů:
$ git add JMENO-SOUBORU $ git reset JMENO-SOUBORU $ git commit
Historie rezpozitáře:
$ git log $ git show IDENTIFIKATOR-ULOZENE-ZMENY
Čtení repozitářů ostatních čarodějů[editovat | editovat zdroj]
Čtení úzce souvisí se sebevzděláváním. Čtení kouzelných vět ostatních čarodějů obohacuje čaroděje v chápání kouzelného jazyka a způsobů řešení problémů. Čtení historie repozitáře v tom, jak se repozitáře spravují, jak se kouzelné věty vylepšují.
Když čaroděj zabrousí do repozitáře dalšího čaroděje nebo čarodějky, nejprve si o repozitáři udělá představu. Zkontroluje licenci, čímž na první dobrou odhadne filosofii čaroděje-autora repozitáře. Pak se podívá do readme, aby si udělal přehled o tom, o čem repozitář je, a jak složité je repozitář použít (pro řešení problému, který repozitář řeší). Prohlédnutím historie repozitáře čaroděj zjistí kdo, jak aktivně a jakým způsobem se na vývoji repozitáře podílí. Čtení zdrojového kódu, tedy kouzelných vět v dopisech pro kouzelnou hůlku, je až poslední věc, kterou čaroděj dělá, když se chce zorientovat v repozitáři dalšího čaroděje.
Mezi čarodějnické konvence, které čarodějové dodržují, protože to zjednodušuje jejich spolupráci, patří i to, že když čaroděj vymýšlí nová kouzelná slova nebo když zaznamenává historii repozitáře, píše anglicky. Navíc, hodně kouzelných slov kouzelných jazyků je převzata z angličtiny. Díky této konvenci si rozumí čarodějové a čarodějky celého světa.
Čarodějové svoje repozitáře sdílení přes speciální webové stránky, jako je třeba https://codeberg.org/Neprogramator/greater-than. Pokud ostatní čarodějové znají odkaz, mohou si repozitář zkopírovat k sobě také přes program Git:
$ git clone https://codeberg.org/Neprogramator/greater-than.git Cloning into 'greater-than'... remote: Enumerating objects: 7, done. remote: Counting objects: 100% (7/7), done. remote: Compressing objects: 100% (7/7), done. remote: Total 7 (delta 1), reused 0 (delta 0), pack-reused 0 Receiving objects: 100% (7/7), done. Resolving deltas: 100% (1/1), done.
Jak si udělat představu o repozitáři greater-than?
Přepnout se do adresáře greater-than a zobrazit soubory:
$ cd greater-than/ $ ls greater-than.rkt LICENSE README
Zobrazit licenci:
$ cat LICENSE Copyright (c) 2024 Jméno Čaroděje Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
a readme:
$ cat README What is greater, 20 or the number? Simple solution of the following problem: > There is constant, "twenty", with assigned value of 20. Then, there is a > procedure "greater-than" that takes single numeric parameter "the-number": if > "the-number" is greater than "twenty", the "greater-than" procedure returns > the text "Větší je the-number." (where "the-number" is the actual value of > "the-number" variable), and "Větší je 20." otherwise. For more information see Czech wikibook "Neprogramátor": https://cs.wikibooks.org/wiki/Neprogram%C3%A1tor/%C4%8Carod%C4%9Bjnick%C3%A9_%C5%99emeslo:_zdrojov%C3%A9_k%C3%B3dy_a_repozit%C3%A1%C5%99
Zobrazit historii repozitáře:
$ git log
commit fe9a7dba747f7751ebb79d14d15264dc52c588c3 (HEAD -> master, origin/master, origin/HEAD)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Mon Jan 22 23:25:07 2024 +0100
Add "What is greater, 20 or the number?" solution
commit 69d7335ad90d84e437e6e342d46d19ba25fea98a
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Mon Jan 22 23:25:02 2024 +0100
Add license, readme
Zobrazit úplně první změnu:
$ git show 69d7335ad90d84e437e6e342d46d19ba25fea98a
commit 69d7335ad90d84e437e6e342d46d19ba25fea98a
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Mon Jan 22 23:25:02 2024 +0100
Add license, readme
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..1d939ff
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2024 Jméno Čaroděje
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README b/README
new file mode 100644
index 0000000..2ffd865
--- /dev/null
+++ b/README
@@ -0,0 +1,11 @@
+What is greater, 20 or the number?
+
+Simple solution of the following problem:
+
+> There is constant, "twenty", with assigned value of 20. Then, there is a
+> procedure "greater-than" that takes single numeric parameter "the-number": if
+> "the-number" is greater than "twenty", the "greater-than" procedure returns
+> the text "Větší je the-number." (where "the-number" is the actual value of
+> "the-number" variable), and "Větší je 20." otherwise.
+
+For more information see Czech wikibook "Neprogramátor": https://cs.wikibooks.org/wiki/Neprogram%C3%A1tor/%C4%8Carod%C4%9Bjnick%C3%A9_%C5%99emeslo:_zdrojov%C3%A9_k%C3%B3dy_a_repozit%C3%A1%C5%99
Zobrazit úplně poslední změnu:
$ git show
commit fe9a7dba747f7751ebb79d14d15264dc52c588c3 (HEAD -> master, origin/master, origin/HEAD)
Author: Jméno Čaroděje <email@carodeje.xyz>
Date: Mon Jan 22 23:25:07 2024 +0100
Add "What is greater, 20 or the number?" solution
diff --git a/greater-than.rkt b/greater-than.rkt
new file mode 100644
index 0000000..599fa5c
--- /dev/null
+++ b/greater-than.rkt
@@ -0,0 +1,9 @@
+#lang racket
+; What is greater, 20 or the number?
+(define twenty 20)
+(define (greater-than the-number)
+ (if (> the-number twenty)
+ (string-append "Větší je " (number->string the-number) ".")
+ (string-append "Větší je " (number->string twenty) ".")))
+(greater-than 11)
+(greater-than 27)
| Čarodějnické řemeslo: zdrojové kódy a repozitář | Neprogramátor/Kouzelné lektvary: spustitelné soubory a testy ► |