Skip to content
Permalink
Browse files

Remove deprecated methods & comment all classes

  • Loading branch information
cdlm committed Feb 21, 2019
1 parent 3ee7cfb commit 1aa45df5538343deb3f6ae3b3f13cae50179bdd4
@@ -1,5 +1,5 @@
"
A thin layer to hook Clap into the existing command-line system
I hook Clap into the existing command-line handlers system.
"
Class {
#name : #ClapCommandLineHandler,
@@ -1,3 +1,6 @@
"
I evaluate code passed via standard input or as arguments from the command line.
"
Class {
#name : #ClapCodeEvaluator,
#superclass : #Object,
@@ -23,7 +26,7 @@ ClapCodeEvaluator class >> evaluate [
multiple: true;
meaning: [ :match | "let's copy all the bytes, twice, because the VM assumes some 8-bit encoding…"
String space join: (match allOccurrencesCollect: #word) ];
defaultMeaning: [ :match | "in the absence of an explicit argument, read from standard input"
implicitMeaning: [ :match | "in the absence of an explicit argument, read from standard input"
match context stdin upToEnd ]);
meaning: [ :args |
args atName: 'help' ifFound: [ :help | help value; exitSuccess ].
@@ -1,3 +1,6 @@
"
I report release and version information about the image and VM, in various formats.
"
Class {
#name : #ClapPharoVersion,
#superclass : #Object,
@@ -41,7 +41,7 @@ ClapCommand class >> forHelp [
add: ((ClapPositional withName: 'topic')
description: 'The subcommand to document (defaults to the current one)';
meaning: [ :pos :cmd | cmd subcommandNamed: pos word ifNone: nil ];
defaultMeaning: [ :pos :cmd | cmd ]);
implicitMeaning: [ :pos :cmd | cmd ]);

meaning: [ :match | | doc parent query topic |
doc := ClapDocumenter on: match context stdout.
@@ -1,3 +1,8 @@
"
I am a match for a composite parameter specification, and thus cover a (possibly empty) range of words in the arguments sequence.
I provide methods for querying and accessing the matches of my specification's children parameters.
"
Class {
#name : #ClapCompositeMatch,
#superclass : #ClapExplicit,
@@ -1,9 +1,11 @@
"
I represent the (stateful) context in which command parsing happens.
Most importantly I own a stream over the sequence of arguments to parse.
I represent the (stateful) context in which command parsing & execution are happening.
My specification is the root command or parameter that will be matched against the the sequence of arguments I receive.
To enable dependency injection, all command code should ask me for any external resource (e.g. exiting, error handling, I/O streams).
For example, the command ""eval '1 + 2' "" is represented by this:
For example, the command invocation ""eval '1 + 2' "" is represented by this:
ClapContext on: #('eval' '1 + 2')
"
Class {
#name : #ClapContext,
@@ -1,3 +1,8 @@
"
I wrap a stream and generate documentation in a concrete format.
The intent is that sister classes will implement various concrete formats (HTML, Man page, LaTeX, colored terminal output…)
"
Class {
#name : #ClapDocumentationFormatter,
#superclass : #Object,
@@ -1,3 +1,8 @@
"
I generate the documentation for a parameter.
I handle the general semantic structure of the documentation, but delegate the actual format to a formatter.
"
Class {
#name : #ClapDocumenter,
#superclass : #Object,
@@ -1,3 +1,8 @@
"
I represent an explicit match over words in the argument sequence, which constitutes an explicit occurrence of my specification.
My instances have a value, given by the meaning block of my specification.
"
Class {
#name : #ClapExplicit,
#superclass : #ClapSubExpression,
@@ -1,5 +1,6 @@
"
I represent the concrete manifestation of a formal parameter during a command activation.
I am a concrete manifestation (a match) of my specification (a ClapParameter) in the context of a specific command-line invocation.
"
Class {
#name : #ClapExpression,
@@ -1,3 +1,9 @@
"
I represent the non-occurrence of a parameter in the argument sequence.
My instances are only created on demand in response to a query for a parameter that was not recognized in the argument sequence, i.e. it was omitted.
When evaluated with #value or #value:, my meaning is given by the implicit meaning block of my specification.
"
Class {
#name : #ClapImplicit,
#superclass : #ClapSubExpression,
@@ -1,3 +1,6 @@
"
I validate a Clap context by checking that it has matched completely, i.e. no word remains unmatched by a parameter.
"
Class {
#name : #ClapLeftoversValidation,
#superclass : #ClapValidation,
@@ -1,5 +1,5 @@
"
I represent a class which represents a failed match.
I am a failed match of my specification at a given word of the arguments sequence.
"
Class {
#name : #ClapMismatch,
@@ -1,3 +1,6 @@
"
I am a match for a named composite parameter; I cover at least one word (corresponding to one of my specification's aliases).
"
Class {
#name : #ClapNamedMatch,
#superclass : #ClapCompositeMatch,
@@ -72,24 +72,6 @@ ClapParameter >> canonicalName: aString [
canonicalName := aString
]

{ #category : #accessing }
ClapParameter >> defaultMeaning [
self
deprecated: 'Renamed to #implicitMeaning'
transformWith: '`@receiver defaultMeaning' -> '`@receiver implicitMeaning'.

^ self implicitMeaning
]

{ #category : #initialization }
ClapParameter >> defaultMeaning: aBlock [
self
deprecated: 'Renamed to #implicitMeaning:'
transformWith: '`@receiver defaultMeaning: `@block' -> '`@receiver implicitMeaning: `@block'.

self implicitMeaning: aBlock
]

{ #category : #accessing }
ClapParameter >> description [
^ description
@@ -1,3 +1,7 @@
"
I am a node in the match tree.
My parent is either the match I'm a child of, or the context for the whole command invocation.
"
Class {
#name : #ClapSubExpression,
#superclass : #ClapExpression,
@@ -1,3 +1,7 @@
"
I represent a validation criterium that various subjects might have to pass at a later point.
My subclasses implement specific validations for Clap parameters.
"
Class {
#name : #ClapValidation,
#superclass : #Object,
@@ -1,3 +1,7 @@
"
I am the result of applying a validation to a given subject.
If the subject does not pass my criterium, I can provide a helpful description why.
"
Class {
#name : #ClapValidationDiagnostic,
#superclass : #Object,
@@ -16,7 +20,7 @@ ClapValidationDiagnostic class >> of: aValidation subject: anExpression [
yourself
]

{ #category : #'as yet unclassified' }
{ #category : #accessing }
ClapValidationDiagnostic >> description [
^ validation failureDescriptionFor: subject
]
@@ -1,3 +1,6 @@
"
I aggregate multiple validation diagnostics together.
"
Class {
#name : #ClapValidationReport,
#superclass : #Object,
@@ -1,3 +1,6 @@
"
I am a leaf match, covering a single word of the argument sequence.
"
Class {
#name : #ClapWordMatch,
#superclass : #ClapExplicit,
@@ -1,11 +1,11 @@
"
Examples and demos of Clap commands (see class side, protocol commandline). Each of those methods builds and returns a command specification, which you can then run or just match against an actual invocation (an array of strings, as would be passed by a shell).
Arbitrary command instances can be run as do-its, e.g.:
ClapCommandLineExamples hello runWith: #('hello' 'Pharo').
ClapCommandLineExamples git runWith: #('git' 'help' 'remote').
To inspect the matches without activating the commands, replace #runWith: with #match:
Arbitrary command instances can be run as do-its, but pay attention that text printed on the standard output will go nowhere unless the VM was launched from a terminal window:
ClapCommandLineExamples hello activateWith: #('hello' 'Pharo').
ClapCommandLineExamples git activateWith: #('git' 'help' 'remote').
To inspect the matches without activating the commands, replace #activateWith: with #match:
ClapCommandLineExamples hello match: #('hello' 'Pharo').
ClapCommandLineExamples git match: #('git' 'help' 'remote').
@@ -61,6 +61,13 @@ ClapCommandLineExamples class >> hello [
add: ClapFlag forHelp;
add: ((ClapFlag withName: 'whisper') description: 'Greet discretely');
add: ((ClapFlag withName: 'shout') description: 'Greet loudly');
add:
((ClapFlag withName: 'language')
description: 'Select language of greeting';
add: ((ClapPositional withName: 'langCode')
meaning: [ :pos | pos word asSymbol ];
implicitMeaning: [ #en ]);
meaning: [ :flag | (flag atName: 'langCode') value ]);
add:
((ClapPositional withName: 'who')
description: 'Recipient of the greetings';
@@ -88,6 +95,36 @@ ClapCommandLineExamples >> argumentAt: argumentName [
^ (arguments atName: argumentName) value
]

{ #category : #running }
ClapCommandLineExamples >> defaultLanguage [
^ #en
]

{ #category : #running }
ClapCommandLineExamples >> greeting [
| langs |
langs := self greetingTranslations.
^ langs at: self language
ifAbsent: [ langs at: self defaultLanguage ]
]

{ #category : #running }
ClapCommandLineExamples >> greetingTranslations [
^ {
#en -> 'hello'.
#eo -> 'saluton'.
#es -> 'hola'.
#fr -> 'bonjour'.
#uk -> 'pryvit'.
#pt -> 'olá'
} asDictionary
]

{ #category : #running }
ClapCommandLineExamples >> language [
^ self argumentAt: 'language'
]

{ #category : #'accessing - private' }
ClapCommandLineExamples >> outStream [
^ outStream ifNil: [ outStream := VTermOutputDriver on: arguments context stdout ]
@@ -100,15 +137,15 @@ ClapCommandLineExamples >> recipients [

{ #category : #running }
ClapCommandLineExamples >> sayHello [
arguments validateAll.
"arguments validateAll."
self sayHelloOn: self outStream
]

{ #category : #running }
ClapCommandLineExamples >> sayHelloOn: aStream [
self recipients do: [ :each |
aStream
<< (self voice: 'hello, ' , each);
<< (self voice: self greeting , ', ' , each);
lf ]
]

0 comments on commit 1aa45df

Please sign in to comment.
You can’t perform that action at this time.